CLI 参考

CodeBuddy Code 命令行工具完整参考手册，包含所有命令和参数说明。

CLI 命令

命令	说明	示例
`codebuddy`	启动交互式 REPL	`codebuddy`
`codebuddy "查询"`	带初始提示词启动 REPL	`codebuddy "解释这个项目"`
`codebuddy -p "查询"`	通过 SDK 查询后退出	`codebuddy -p "解释这个函数"`
`cat 文件 \| codebuddy -p "查询"`	处理管道内容	`cat logs.txt \| codebuddy -p "分析日志"`
`codebuddy -c`	继续最近的对话	`codebuddy -c`
`codebuddy -c -p "查询"`	通过 SDK 继续对话	`codebuddy -c -p "检查类型错误"`
`codebuddy -r "<session-id>" "查询"`	通过 ID 恢复会话	`codebuddy -r "abc123" "完成这个 MR"`
`codebuddy update`	更新到最新版本	`codebuddy update`
`codebuddy mcp`	配置 Model Context Protocol (MCP) 服务器	参见 CodeBuddy Code MCP 文档

CLI 参数

自定义 CodeBuddy Code 行为的命令行参数：

参数	说明	示例
`--add-dir`	添加额外的工作目录供 CodeBuddy 访问（验证每个路径是否存在）	`codebuddy --add-dir ../apps ../lib`
`--agents`	通过 JSON 动态定义自定义子代理（格式见下文）	`codebuddy --agents '{"reviewer":{"description":"审查代码","prompt":"你是代码审查员"}}'`
`--allowedTools`	除了settings.json 文件外,无需提示用户即可允许的工具列表	`"Bash(git log:)" "Bash(git diff:)" "Read"`
`--disallowedTools`	除了settings.json 文件外,应禁止使用的工具列表	`"Bash(git log:)" "Bash(git diff:)" "Edit"`
`--print`, `-p`	打印响应后退出,不进入交互模式	`codebuddy -p "查询"`
`--system-prompt`	用自定义文本替换整个系统提示词（在交互和打印模式下都可用）	`codebuddy --system-prompt "你是 Python 专家"`
`--system-prompt-file`	从文件加载系统提示词,替换默认提示词(仅打印模式)	`codebuddy -p --system-prompt-file ./custom-prompt.txt "查询"`
`--append-system-prompt`	在默认系统提示词末尾追加自定义文本（在交互和打印模式下都可用）	`codebuddy --append-system-prompt "始终使用 TypeScript"`
`--output-format`	指定打印模式的输出格式(选项: `text`, `json`, `stream-json`)	`codebuddy -p "查询" --output-format json`
`--input-format`	指定打印模式的输入格式(选项: `text`, `stream-json`)	`codebuddy -p --output-format json --input-format stream-json`
`--json-schema`	Agent 完成工作流后获取匹配 JSON Schema 的验证 JSON 输出	`codebuddy -p --json-schema '{"type":"object","properties":{...}}' "查询"`
`--include-partial-messages`	在输出中包含部分流式事件（需要 `--print` 和 `--output-format=stream-json`)	`codebuddy -p --output-format stream-json --include-partial-messages "查询"`
`--verbose`	启用详细日志记录,显示完整的轮次输出(在打印和交互模式下都有助于调试)	`codebuddy --verbose`
`--max-turns`	限制非交互模式下的代理轮次数	`codebuddy -p --max-turns 3 "查询"`
`--model`	使用别名设置当前会话的模型,如最新模型的别名(`sonnet` 或 `opus`)或模型全名	`codebuddy --model gpt-5`
`--permission-mode`	以指定的权限模式开始	`codebuddy --permission-mode plan`
`--permission-prompt-tool`	指定在非交互模式下处理权限提示的 MCP 工具	`codebuddy -p --permission-prompt-tool mcp_auth_tool "查询"`
`--resume`	通过 ID 恢复特定会话,或在交互模式下选择	`codebuddy --resume abc123 "查询"`
`--continue`	加载当前目录中最近的对话	`codebuddy --continue`
`-y` / `--dangerously-skip-permissions`	跳过权限提示（谨慎使用）	`codebuddy -y` 或 `codebuddy --dangerously-skip-permissions`
`--ide`	启动时自动连接到 IDE（如果恰好有一个有效的 IDE 可用且打开了当前工作目录）	`codebuddy --ide`
`--sandbox`	在沙箱中运行 CodeBuddy（详见下方沙箱模式)	`codebuddy --sandbox "分析项目"`
`--debug`	启用调试模式,支持可选的类别过滤	`codebuddy --debug`

重要提示：在使用 -p/--print 参数进行非交互式执行时,涉及文件读写、命令执行、网络请求等操作通常需要添加 -y （或 --dangerously-skip-permissions)参数才能执行，否则操作会被阻止。

TIP

`--output-format json` 参数特别适用于脚本和自动化，允许您以编程方式解析 CodeBuddy 的响应。

Agents 参数格式

--agents 参数接受定义一个或多个自定义子代理的 JSON 对象。每个子代理需要一个唯一的名称（作为键）和一个包含以下字段的定义对象：

字段	必需	说明
`description`	是	何时应调用子代理的自然语言描述
`prompt`	是	指导子代理行为的系统提示词
`tools`	否	子代理可以使用的特定工具数组（如 `["Read", "Edit", "Bash"]`)。省略则继承所有工具
`model`	否	要使用的模型别名: `sonnet`、`opus` 或 `haiku`。省略则使用默认子代理模型

示例：

bash

codebuddy --agents '{
  "code-reviewer": {
    "description": "专业代码审查员。代码更改后主动使用。",
    "prompt": "你是高级代码审查员。专注于代码质量、安全性和最佳实践。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "错误和测试失败的调试专家。",
    "prompt": "你是专业调试人员。分析错误，识别根本原因并提供修复方案。"
  }
}'

有关创建和使用子代理的更多详细信息，请参见子代理文档。

系统提示词参数

CodeBuddy Code 提供三个自定义系统提示词的参数，每个参数用途不同：

参数	行为	模式	使用场景
`--system-prompt`	替换整个默认提示词	交互 + 打印模式	完全控制 CodeBuddy 的行为和指令
`--system-prompt-file`	用文件内容替换	仅打印模式	从文件加载提示词以确保可重现性和版本控制
`--append-system-prompt`	追加到默认提示词	交互 + 打印模式	添加特定指令同时保留默认 CodeBuddy Code 行为

何时使用：

--system-prompt：当您需要完全控制 CodeBuddy 的系统提示词时使用。这会移除所有默认 CodeBuddy Code 指令，给您一个空白画布。
bash
```
codebuddy --system-prompt "你是只编写带类型注解代码的 Python 专家"
```
--system-prompt-file：当您想从文件加载自定义提示词时使用，适用于团队一致性或版本控制的提示词模板。
bash
```
codebuddy -p --system-prompt-file ./prompts/code-review.txt "审查这个 MR"
```
--append-system-prompt：当您想添加特定指令同时保留 CodeBuddy Code 的默认功能时使用。这是大多数用例的最安全选项。
bash
```
codebuddy --append-system-prompt "始终使用 TypeScript 并包含 JSDoc 注释"
```

NOTE

`--system-prompt` 和 `--system-prompt-file` 互斥。不能同时使用这两个参数。

TIP

对于大多数用例，建议使用 `--append-system-prompt`,因为它在添加自定义需求的同时保留了 CodeBuddy Code 的内置功能。仅当需要完全控制系统提示词时才使用 `--system-prompt` 或 `--system-prompt-file`。

沙箱模式（Beta)

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 模式： 连接到远程创建的沙箱

沙箱使用示例

bash

# 容器沙箱 （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 "连接到远程沙箱"

沙箱环境变量

bash

E2B_API_KEY                          E2B API 密钥 （E2B 沙箱必需）
E2B_TEMPLATE                         E2B 模板 ID （默认： base)
CODEBUDDY_SANDBOX_IMAGE              自定义 Docker 镜像 （容器沙箱）

下一步

掌握 CLI 命令后，您可以：

学习交互模式 - 掌握键盘快捷键和技巧
探索斜杠命令 - 了解内置命令
Skills 技能系统 - 扩展 AI 专业能力
学习 MCP 集成 - 扩展工具能力

精确的命令行操作是高效开发的基础

CLI 参考 ​

CLI 命令 ​

CLI 参数 ​

Agents 参数格式 ​

系统提示词参数 ​

沙箱模式 （Beta) ​

沙箱参数 ​

沙箱使用示例 ​

沙箱环境变量 ​

下一步 ​

CLI 参考

CLI 命令

CLI 参数

Agents 参数格式

系统提示词参数

沙箱模式（Beta)

沙箱参数

沙箱使用示例

沙箱环境变量

下一步