# 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 文档](./mcp.md)      |
| `codebuddy daemon start`           | 启动 Daemon 守护进程                     | `codebuddy daemon start --port 8080`           |
| `codebuddy daemon stop`            | 停止 Daemon                              | `codebuddy daemon stop`                        |
| `codebuddy daemon status`          | 查看 Daemon 状态                         | `codebuddy daemon status`                      |
| `codebuddy daemon restart`         | 重启 Daemon                              | `codebuddy daemon restart`                     |
| `codebuddy ps`                     | 列出所有活跃 Worker 进程                 | `codebuddy ps`                                 |
| `codebuddy logs <pid\|name>`       | 查看 Worker 日志                         | `codebuddy logs feature-x`                     |
| `codebuddy attach <pid\|name>`     | 附加到后台 Worker                        | `codebuddy attach feature-x`                   |
| `codebuddy kill <pid\|name>`       | 终止 Worker 进程                         | `codebuddy kill feature-x`                     |

## CLI 参数

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

| 参数                             | 说明                                                                                                                              | 示例                                                                                               |
| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| `--add-dir`                      | 添加额外的工作目录供 CodeBuddy 访问（验证每个路径是否存在）                                                                         | `codebuddy --add-dir ../apps ../lib`                                                               |
| `--agent`                        | 指定当前会话使用的 agent 名称（内置或自定义 agent），优先级高于 settings.json 的 `agent` 配置                                         | `codebuddy --agent my-reviewer`                                                                    |
| `--agents`                       | 通过 JSON 动态定义自定义[子代理](./sub-agents.md)（格式见下文）                                                                     | `codebuddy --agents '{"reviewer":{"description":"审查代码","prompt":"你是代码审查员"}}'`            |
| `--allowedTools`                 | 除了[settings.json 文件](./settings.md)外,无需提示用户即可允许的工具列表                                                          | `"Bash(git log:*)" "Bash(git diff:*)" "Read"`                                                      |
| `--disallowedTools`              | 除了[settings.json 文件](./settings.md)外,应禁止使用的工具列表                                                                    | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"`                                                      |
| `--tools`                        | 限制可用的内置工具集（白名单）。空字符串 `""` 禁用所有内置工具，`"default"` 使用全部工具，或指定逗号分隔的工具名                      | `codebuddy --tools "Bash,Read,Edit"`                                                               |
| `--print`, `-p`                  | 打印响应后退出,不进入交互模式                             | `codebuddy -p "查询"`                                                                              |
| `--settings`                     | 从 JSON 文件或 JSON 字符串加载额外的设置配置                                                                                       | `codebuddy --settings '{"model":"gpt-5"}' "查询"`                                                  |
| `--setting-sources`              | 指定要加载的设置源,逗号分隔（可选值: `user`, `project`, `local`）。默认: `user,project,local`                                      | `codebuddy --setting-sources project,local "查询"`                                                 |
| `--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`                  | 使用 JSON Schema 验证结构化输出。示例: `'{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}'`                                                                                   | `codebuddy -p --output-format json --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`                                                                          |
| `--text-to-image-model`          | 设置文生图功能使用的模型 ID                                                                                                           | `codebuddy --text-to-image-model your-image-model`                                                 |
| `--image-to-image-model`         | 设置图生图功能使用的模型 ID                                                                                                           | `codebuddy --image-to-image-model your-edit-model`                                                 |
| `--permission-mode`              | 以指定的[权限模式](./iam.md#permission-modes)开始                                                                                 | `codebuddy --permission-mode plan`                                                                 |
| `--subagent-permission-mode`     | 设置 subagent/团队成员的默认权限模式，覆盖从主 session 继承的模式                                                                  | `codebuddy --subagent-permission-mode bypassPermissions`                                           |
| `--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（详见下方[沙箱模式](#沙箱模式-beta))                                                                        | `codebuddy --sandbox "分析项目"`                                                                   |
| `--debug`                        | 启用调试模式,支持可选的类别过滤                                                                                                   | `codebuddy --debug`                                                                                |
| `--worktree [name]`              | 在独立的 git worktree 中运行（详见 [Worktree 文档](./worktree.md)）                                                               | `codebuddy --worktree` 或 `codebuddy --worktree my-feature`                                        |
| `--tmux`                         | 在 tmux 会话中运行（与 `--worktree` 配合使用）                                                                                     | `codebuddy --worktree --tmux`                                                                      |
| `--plugin-dir <dirs...>`         | 从本地目录加载插件（用于开发/测试），可指定多个路径。详见 [插件文档](plugins.md)                                                     | `codebuddy --plugin-dir ./my-plugin ../other-plugin`                                               |
| `--bg`                           | 后台运行会话（detached 模式），日志输出到 `~/.codebuddy/logs/`。详见 [Daemon 文档](daemon.md)                                      | `codebuddy --bg "实现登录页面"`                                                                    |
| `--name <name>`                  | 后台会话名称（与 `--bg` 配合使用，便于通过 `ps`/`logs`/`kill` 查找）                                                               | `codebuddy --bg --name feature-x "实现功能"`                                                       |
| `--serve`                        | 启动 HTTP 服务（Web UI、REST API、ACP 协议）                                                                                       | `codebuddy --serve --port 8080`                                                                    |

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

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

### Agents 参数格式

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

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

示例：

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

有关创建和使用子代理的更多详细信息，请参见[子代理文档](./sub-agents.md)。

### 系统提示词参数

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` 互斥。不能同时使用这两个参数。
</Note>

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

## 沙箱模式 （Beta)

> **Beta 功能**: Sandbox 功能目前处于 Beta 阶段。
> 
> **详细文档**：查看 [Bash 沙箱](./bash-sandboxing.md) 获取沙箱隔离功能说明。

### 沙箱参数

```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 命令后，您可以：

- **[学习交互模式](./interactive-mode.md)** - 掌握键盘快捷键和技巧
- **[探索斜杠命令](./slash-commands.md)** - 了解内置命令
- **[Skills 技能系统](./skills.md)** - 扩展 AI 专业能力
- **[学习 MCP 集成](./mcp.md)** - 扩展工具能力

---

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