CodeBuddy Code 命令行工具完整参考手册，包含所有命令和参数说明。
命令 | 说明 | 示例 |
| 启动交互式 REPL |
|
| 带初始提示词启动 REPL |
|
| 通过 SDK 查询后退出 |
|
| 处理管道内容 |
|
| 继续最近的对话 |
|
| 通过 SDK 继续对话 |
|
| 通过 ID 恢复会话 |
|
| 更新到最新版本 |
|
| 配置 Model Context Protocol (MCP) 服务器 | |
| 按来源分组列出全部已配置子代理 |
|
| 启动 Daemon 守护进程 |
|
| 停止 Daemon |
|
| 查看 Daemon 状态 |
|
| 重启 Daemon |
|
| 注册为系统服务（登录自启） |
|
| 移除系统服务注册 |
|
| 打印 |
|
| 打印当前生效的 |
|
| 用 lite 模型审视你的自定义 |
|
| 列出所有活跃 Worker 进程 |
|
| 查看 Worker 日志 |
|
| 附加到后台 Worker |
|
| 终止 Worker 进程 |
|
自定义 CodeBuddy Code 行为的命令行参数：
参数 | 说明 | 示例 |
| 添加额外的工作目录供 CodeBuddy 访问（验证每个路径是否存在） |
|
| 指定当前会话使用的 agent 名称（内置或自定义 agent），优先级高于 settings.json 的 |
|
| 通过 JSON 动态定义自定义子代理（格式见下文） |
|
| 除了 settings.json 文件外，无需提示用户即可允许的工具列表 |
|
| 除了 settings.json 文件外，应禁止使用的工具列表 |
|
| 限制可用的内置工具集（白名单）。空字符串 |
|
| 从 JSON 文件或 JSON 字符串加载 MCP 服务器配置 |
|
| 仅使用 |
|
| 仅在内存中保留会话上下文，不创建或更新本地 transcript；仍可以只读加载已有会话 |
|
| 打印响应后退出，不进入交互模式 |
|
| 从 JSON 文件或 JSON 字符串加载额外的设置配置 |
|
| 指定要加载的设置源，逗号分隔（可选值: |
|
| 用自定义文本替换整个系统提示词（在交互和打印模式下都可用） |
|
| 从文件加载系统提示词，替换默认提示词(仅打印模式) |
|
| 在默认系统提示词末尾追加自定义文本（在交互和打印模式下都可用） |
|
| 指定打印模式的输出格式(选项: |
|
| 指定打印模式的输入格式(选项: |
|
| 使用 JSON Schema 验证结构化输出。示例: |
|
| 在输出中包含部分流式事件（需要 |
|
| 启用详细日志记录，显示完整的轮次输出(在打印和交互模式下都有助于调试) |
|
| 限制非交互模式下的代理轮次数 |
|
| 使用别名设置当前会话的模型，如最新模型的别名（ |
|
| 设置文生图功能使用的模型 ID |
|
| 设置图生图功能使用的模型 ID |
|
| 以指定的权限模式开始。常用值： |
|
| 设置 subagent/团队成员的默认权限模式，覆盖从主 session 继承的模式。支持 |
|
| 指定在非交互模式下处理权限提示的 MCP 工具 |
|
| 通过 ID 恢复特定会话，或在交互模式下选择 |
|
| 加载当前目录中最近的对话 |
|
| 跳过权限提示（谨慎使用） |
|
| 启动时自动连接到 IDE（如果恰好有一个有效的 IDE 可用且打开了当前工作目录） |
|
| 在沙箱中运行 CodeBuddy（详见下方沙箱模式) |
|
| 启用调试模式，支持可选的类别过滤 |
|
| 在独立的 git worktree 中运行（详见 Worktree 文档） |
|
| 在 tmux 会话中运行（与 |
|
| 从本地目录加载插件（用于开发/测试），可指定多个路径。详见 插件文档 |
|
| 后台运行会话（detached 模式），日志输出到 |
|
| 后台会话名称（与 |
|
| 启动 HTTP 服务（Web UI、REST API、ACP 协议） |
|
| 以预热待命模式启动：先完成启动初始化后挂起，等待外部通过 IPC 唤醒（唤醒时才绑定工作目录）。用于消除会话拉起时的冷启动等待。默认关闭。 |
|
| 预热 IPC 端点标识（默认取进程 PID），用于构造本地 socket/管道地址。配合 |
|
重要提示：
在使用 -p/--print 进行非交互式执行时，涉及文件读写、命令执行、网络请求等操作必须有一个明确的权限策略：最常见的是 -y / --dangerously-skip-permissions，也可以使用 --permission-mode auto、--permission-mode dontAsk、预先配置的 permissions.allow 规则，或专门的权限提示 MCP 工具。否则需要人工确认的操作会被阻止。
说明：
--output-format json 参数特别适用于脚本和自动化，允许您以编程方式解析 CodeBuddy 的响应。
--agents 参数接受定义一个或多个自定义子代理的 JSON 对象。每个子代理需要一个唯一的名称（作为键）和一个包含以下字段的定义对象：
字段 | 是否必需 | 说明 |
| 是 | 何时应调用子代理的自然语言描述 |
| 是 | 指导子代理行为的系统提示词 |
| 否 | 子代理可以使用的特定工具数组（如 |
| 否 | 子代理禁止使用的工具数组（黑名单），与 session 级 |
| 否 | 模型 ID、名称或别名、场景变体 |
| 否 | 推理强度： |
| 否 | 子代理最大执行轮次（正整数）。优先级：env |
| 否 | 设为 |
| 否 | 该 agent 作为主会话 agent（ |
| 否 | 持久记忆作用域： |
示例：
codebuddy --agents '{ "code-reviewer": { "description": "专业代码审查员。代码更改后主动使用。", "prompt": "你是高级代码审查员。专注于代码质量、安全性和最佳实践。", "tools": ["Read"， "Grep"， "Glob"， "Bash"], "model": "lite" }， "debugger": { "description": "错误和测试失败的调试专家。", "prompt": "你是专业调试人员。分析错误，识别根本原因并提供修复方案。" }}'
有关创建和使用子代理的更多详细信息，请参见子代理文档。
CodeBuddy Code 提供三个自定义系统提示词的参数，每个参数用途不同：
参数 | 行为 | 模式 | 使用场景 |
| 替换整个默认提示词 | 交互 + 打印模式 | 完全控制 CodeBuddy 的行为和指令 |
| 用文件内容替换 | 仅打印模式 | 从文件加载提示词以确保可重现性和版本控制 |
| 追加到默认提示词 | 交互 + 打印模式 | 添加特定指令同时保留默认 CodeBuddy Code 行为 |
何时使用：
--system-prompt：当您需要完全控制 CodeBuddy 的系统提示词时使用。这会移除所有默认 CodeBuddy Code 指令，给您一个空白画布。
codebuddy --system-prompt "你是只编写带类型注解代码的 Python 专家"
--system-prompt-file：当您想从文件加载自定义提示词时使用，适用于团队一致性或版本控制的提示词模板。
codebuddy -p --system-prompt-file ./prompts/code-review.txt "审查这个 MR"
--append-system-prompt：当您想添加特定指令同时保留 CodeBuddy Code 的默认功能时使用。这是大多数用例的最安全选项。
codebuddy --append-system-prompt "始终使用 TypeScript 并包含 JSDoc 注释"
说明：
--system-prompt 和 --system-prompt-file 互斥。不能同时使用这两个参数。
对于大多数用例，建议使用 --append-system-prompt，因为它在添加自定义需求的同时保留了 CodeBuddy Code 的内置功能。仅当需要完全控制系统提示词时才使用 --system-prompt 或 --system-prompt-file。
说明：
Beta 功能: Sandbox 功能目前处于 Beta 阶段。
详细文档：查看 Bash 沙箱 获取沙箱隔离功能说明。
--sandbox [url] 在沙箱中运行 CodeBuddy: - 不带参数或 "container"：使用容器 （Docker/Podman) - 提供完整的 E2B API URL：使用云端沙箱--sandbox-upload-dir 上传当前工作目录到沙箱 （仅 E2B)--sandbox-new 强制创建新沙箱 （忽略缓存的沙箱）--sandbox-id <id> 连接到指定的沙箱 ID 或别名--sandbox-kill 退出时终止沙箱 （默认： 保持运行以便复用）--teleport <value> Teleport 模式： 连接到远程创建的沙箱
# 容器沙箱 （Docker/Podman，自动挂载当前目录）
codebuddy --sandbox "分析这个项目"
# E2B 云端沙箱 （自动复用）
codebuddy --sandbox https://api.e2b.dev "创建 Python web 应用"
# 强制创建新沙箱
codebuddy --sandbox --sandbox-new "从头开始"
# 连接到指定沙箱
codebuddy --sandbox --sandbox-id sb_abc123 "继续工作"
# 退出时清理沙箱
codebuddy --sandbox --sandbox-kill "临时测试"
# Teleport 模式 - 连接到远程创建的沙箱
codebuddy --teleport session_abc123XYZ4567890 "连接到远程沙箱"
E2B_API_KEY E2B API 密钥 （E2B 沙箱必需）E2B_TEMPLATE E2B 模板 ID （默认： base)CODEBUDDY_SANDBOX_IMAGE 自定义 Docker 镜像 （容器沙箱）
掌握 CLI 命令后，您可以：
学习交互模式 - 掌握键盘快捷键和技巧
探索斜杠命令 - 了解内置命令
Skills 技能系统 - 扩展 AI 专业能力
学习 MCP 集成 - 扩展工具能力
