> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 CLI

## TUI 模式

在任意项目根目录运行 `qodercli` 即可进入默认的 TUI（交互式）模式。你可以通过文本与 CLI 对话，也可以通过斜杠命令执行特定功能。

### 输入模式

TUI 提供多种输入模式：

| 命令      | 描述                                  |
| :------ | :---------------------------------- |
| `>`     | 对话模式（默认）。输入任意文本即可与 CLI 对话           |
| `!`     | Bash 模式。在对话模式下输入 `!` 可直接运行 shell 命令 |
| `/`     | 斜杠模式。在对话模式下输入 `/` 可打开并运行内置命令        |
| `\` `⏎` | 按 Enter 开始多行输入                      |

### 内置工具

Qoder CLI 内置 Grep、Read、Write、Bash 等工具，可用于文件/目录操作和 shell 命令执行。

如需了解工具能力和控制方式，见 [工具](/zh/cli/tools)。

### 斜杠命令

通过以下内置斜杠命令快速访问功能和设置：

| 命令               | 描述                                 |
| :--------------- | :--------------------------------- |
| `/login`         | 登录你的 Qoder 账号                      |
| `/help`          | 显示 TUI 帮助                          |
| `/init`          | 在项目中初始化或更新 `AGENTS.md` 记忆文件        |
| `/memory`        | 打开记忆概览，管理用户级、项目级、本地记忆和自动记忆入口       |
| `/quest`         | 执行基于 Spec 的委派任务                    |
| `/review`        | 对本地代码改动进行评审                        |
| `/resume`        | 查看并恢复会话                            |
| `/clear`         | 清除当前会话的历史上下文                       |
| `/compact`       | 总结当前会话的历史上下文                       |
| `/usage`         | 显示当前 Credits 使用情况                  |
| `/status`        | 查看 CLI 状态，包括版本、模型、账号、API 连通性、工具状态等 |
| `/config`        | 查看 Qoder CLI 的系统配置                 |
| `/effort`        | 调整当前模型的思考深度及相关模型参数                 |
| `/agents`        | 子 Agent 命令：查看、创建、管理子 Agent         |
| `/tasks`         | 查看当前正在运行的后台任务                      |
| `/release-notes` | 显示 Qoder CLI 更新日志                  |
| `/vim`           | 打开外部编辑器来编辑输入                       |
| `/feedback`      | 发送 Qoder CLI 相关反馈                  |
| `/quit`          | 退出 TUI                             |
| `/logout`        | 退出你的 Qoder 账号                      |

### 高级启动选项

启动 CLI 时，可以使用以下选项控制行为：

| 命令                   | 说明                   | 示例                                               |
| :------------------- | :------------------- | :----------------------------------------------- |
| `-w`                 | 指定工作区目录              | `qodercli -w /Users/demo/projects/nacos`         |
| `-c`                 | 继续上次会话               | `qodercli -c`                                    |
| `-r`                 | 恢复指定会话               | `qodercli -r *******-c09a-40a9-82a7-a565413fa39` |
| `--allowed-tools`    | 仅允许指定工具              | `qodercli --allowed-tools=Read,Write`            |
| `--disallowed-tools` | 禁止指定工具               | `qodercli --disallowed-tools=Read,Write`         |
| `--max-turns`        | 最大对话轮数               | `qodercli --max-turns=10`                        |
| `--worktree [name]`  | 在独立 Git worktree 中启动 | `qodercli --worktree feature-a`                  |
| `--yolo`             | 跳过权限检查               | `qodercli --yolo`                                |

权限相关的启动参数和设置见 [权限](/zh/cli/permissions)。

## Print 模式

Print 模式是非交互式模式。运行 `qodercli --print` 即可进入，输出会按照 `--output-format` 参数指定的格式打印。

### 参数

全局参数可用于任意命令：

| 参数                   | 说明                         | 示例                                                  |
| :------------------- | :------------------------- | :-------------------------------------------------- |
| `-p`                 | 以非交互方式运行 Agent             | `qodercli -p hi`                                    |
| `--output-format`    | 输出格式：text、json、stream-json | `qodercli --output-format=json`                     |
| `-w`                 | 指定工作区目录                    | `qodercli -w /Users/qoder_user/projects/qoder_demo` |
| `-c`                 | 继续上次会话                     | `qodercli -c`                                       |
| `-r`                 | 恢复指定会话                     | `qodercli -r ********-c09a-40a9-82a7-a565413fa393`  |
| `--allowed-tools`    | 仅允许指定工具                    | `qodercli --allowed-tools=Read,Write`               |
| `--disallowed-tools` | 禁止指定工具                     | `qodercli --disallowed-tools=Read,Write`            |
| `--max-turns`        | 最大对话轮数                     | `qodercli --max-turns=10`                           |
| `--worktree [name]`  | 在独立 Git worktree 中启动       | `qodercli --worktree feature-a -p "Fix login"`      |
| `--yolo`             | 跳过权限检查                     | `qodercli --yolo`                                   |

## Worktree

使用 `--worktree [name]` 可以在独立的 Git worktree 中启动 Qoder CLI 会话。适合在同一个仓库中并行处理多个任务，避免多个会话共享同一个工作目录或改动主检出。

> 要求：在 Git 仓库中运行该命令，并确保本地已安装 Git。

### 在 worktree 中启动

```shell theme={null}
qodercli --worktree feature-a
qodercli --worktree feature-a "Implement the login fix"
qodercli --worktree
```

如果不传 worktree 名称，Qoder CLI 会自动生成一个名称。worktree 名称最多 256 个字符，可以包含字母、数字、点、下划线、短横线和用 `/` 分隔的片段。带 `/` 的名称会在目录名和分支名中转换成 `+`。

创建新的命名 worktree 时，Qoder CLI 会把它放在 `<repo>/.qoder/worktrees/<flattened-name>` 下，并创建名为 `worktree-<flattened-name>` 的临时分支。如果同名 worktree 已存在，Qoder CLI 会直接复用该目录，而不是再创建一个。

新的 worktree 优先基于本地 `origin/HEAD` 指向的默认分支引用创建。如果没有配置 `origin/HEAD`，Qoder CLI 会在能够解析或获取 `origin/main` 时使用它；否则回退到当前 `HEAD`。如果必须从最新远端提交开始，请先执行 `git fetch origin`。

### 复制本地文件

新的 worktree 是干净检出，默认不包含 `.env` 等未跟踪文件。需要把本地文件复制到新 worktree 时，在仓库根目录添加 `.worktreeinclude`：

```text theme={null}
.env
.env.local
config/secrets.json
```

只有同时匹配 `.worktreeinclude` 且已经被 Git 忽略的文件会被复制。项目本地设置 `.qoder/settings.local.json` 存在时会自动复制。

### 恢复和清理

会话结束时，Qoder CLI 会打印 worktree 路径和恢复该会话的命令：

```shell theme={null}
cd <worktree-path> && qodercli --resume <session-id>
```

交互式退出会检查 worktree 中的未提交文件和新增提交。干净的 worktree 可以自动删除；存在本地文件或提交时，退出提示会让你选择保留或删除。删除会丢弃这些改动，并删除临时分支。

如需手动删除 worktree，执行：

```shell theme={null}
git worktree remove <worktree-path>
```

如果不再需要 `worktree-<flattened-name>` 分支，可以单独删除该分支：

```shell theme={null}
git branch -d worktree-<flattened-name>
```

### 在会话中使用 worktree

在已有会话中，也可以要求 Qoder CLI 在隔离的 worktree 中处理任务。它会为当前会话创建并进入 worktree；需要离开时，可以要求它退出 worktree 并恢复原工作目录。

Subagent 也可以使用 worktree 隔离。某个 Markdown Subagent 需要在独立检出里改文件时，在定义中添加 `isolation: worktree`。干净的 Subagent worktree 会在 Subagent 结束后删除；有改动的 worktree 会保留。配置方式见 [子代理](/zh/cli/subagent)。

对于会话中创建的 worktree 和启用 worktree 隔离的 Subagent，`WorktreeCreate` Hook 可以提供自定义 worktree 路径。配套的 `WorktreeRemove` 清理行为见 [Hooks](/zh/cli/hooks)。`--worktree` 启动参数本身要求在 Git 仓库中使用，并使用 Git 创建 worktree。

如果需要完全手动控制目录和分支，可以直接使用 Git 创建 worktree，再在该目录中启动 Qoder CLI：

```shell theme={null}
git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a && qodercli
```

## 记忆

Qoder CLI 通过 `AGENTS.md` 文件和可选的自动记忆在会话间保留上下文。常用文件包括用户级 `~/.qoder/AGENTS.md`、项目级 `${project}/AGENTS.md` 和本地项目级 `${project}/AGENTS.local.md`。

### 自动生成

在目标项目中启动 TUI，并输入 `/init`，即可在项目目录中生成 `AGENTS.md`。

### 手动管理

* 在项目中创建 `AGENTS.md` 并编辑其内容。
* 在 TUI 中输入 `/memory`，管理用户级、项目级和本地记忆文件。
* 自动记忆启用时，可在 `/memory` 面板打开 auto-memory folder，也可输入 `/memory manage` 管理自动保存的记忆文件。

完整说明见 [记忆](/zh/cli/memory)。