> ## 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/07-参考/tools)。

### 斜杠命令

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

| 命令 | 描述 |
| :- | :- |
| `/login` | 登录你的 Qoder 账号 |
| `/help` | 显示 TUI 帮助 |
| `/init` | 在项目中初始化或更新 `AGENTS.md` 记忆文件 |
| `/memory` | 打开记忆概览，管理用户级、项目级、本地记忆和自动记忆入口 |
| `/quest` | 智能工作流编排器，引导你通过专用子代理逐步完成功能开发 |
| `/review` | 对本地代码改动进行评审 |
| `/resume` | 查看并恢复会话 |
| `/clear` | 清除当前会话的历史上下文 |
| `/compact` | 总结当前会话的历史上下文 |
| `/usage` | 显示当前 Credits 使用情况 |
| `/status` | 查看 CLI 状态，包括版本、模型、账号、API 连通性、工具状态等 |
| `/config` | 查看 Qoder CLI 的系统配置 |
| `/effort` | 调整当前模型的思考深度及相关模型参数 |
| `/agents` | 子 Agent 命令：查看、创建、管理子 Agent |
| `/tasks` | 查看当前正在运行的后台任务 |
| `/release-notes` | 显示 Qoder CLI 更新日志 |
| `/vim` | 切换 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` |
| `--tools` | 限制可用的内置工具（`""` 禁用全部、`default` 启用全部） | `qodercli --tools=Read,Edit -p "Fix login"` |
| `--max-turns` | 最大对话轮数 | `qodercli --max-turns=10` |
| `--worktree [name]` | 在独立 Git worktree 中启动 | `qodercli --worktree feature-a` |
| `--yolo` | 跳过权限检查 | `qodercli --yolo` |

权限相关的启动参数和设置见 [权限](/zh/cli/06-配置与安全/permissions)。

## Print 模式

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

### 参数

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

| 参数 | 说明 | 示例 |
| :- | :- | :- |
| `-p` | 以非交互方式运行 Agent | `qodercli -p hi` |
| `-o, --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` |

## Shell 命令前缀

启动 Qoder CLI 前设置 `QODER_SHELL_PREFIX`，可以让受支持的本地 shell 命令通过一个可执行 wrapper 运行。

**macOS 和 Linux**

```shell theme={null}
QODER_SHELL_PREFIX=/absolute/path/to/wrapper qodercli
```

**Windows PowerShell**

```powershell theme={null}
$env:QODER_SHELL_PREFIX = 'C:\absolute\path\to\wrapper.exe'
qodercli
```

**Windows 命令提示符**

```shell theme={null}
set "QODER_SHELL_PREFIX=C:\absolute\path\to\wrapper.exe"
qodercli
```

POSIX 兼容 wrapper 可以按以下方式实现所需的命令转发：

```bash theme={null}
#!/usr/bin/env bash
exec bash -c "$1"
```

wrapper 会收到经过 shell 引号处理的完整生成命令行，并将其作为第一个参数传入（在 POSIX wrapper 中为 `$1`）。wrapper 必须通过 POSIX 兼容 shell 重新解析并执行该参数，而不能将整段参数当作可执行文件路径。上例使用 `exec`，可以保留 stdin、stdout、stderr、退出状态和信号。在 Windows 上，wrapper 必须将第一个参数以 `bash.exe -c <参数>` 的形式交给 Git Bash，并保持相同的进程行为；PowerShell 和 `cmd.exe` 无法正确解析这种命令引号格式。

变量值只能是单个可执行文件路径，不要附加 shell 参数。为确保所有应用前缀的入口行为一致，可执行文件路径不能包含空格后紧跟连字符的序列（` -`）；POSIX shell 前缀解析器会保留该序列。

该前缀作用于 Bash 模式（`!`）、Bash 工具、使用 bash 兼容 shell 的 shell 形态命令 Hook 和自定义状态行命令，以及 stdio MCP 服务；不作用于 exec 形态 Hook、PowerShell Hook 或状态行命令、基于 URL 的 MCP 传输以及交互式 PTY 命令。如果 Qoder CLI 从启动环境继承了 shell 前缀，将 `QODER_SHELL_PREFIX` 显式设为空值可以禁用该前缀。现有权限、信任和 sandbox 检查仍然生效。

## 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 会保留。配置方式见 [Subagent](/zh/cli/04-扩展QoderCLI/subagent)。

对于会话中创建的 worktree 和启用 worktree 隔离的 Subagent，`WorktreeCreate` Hook 可以提供自定义 worktree 路径。配套的 `WorktreeRemove` 清理行为见 [Hooks](/zh/cli/04-扩展QoderCLI/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/04-扩展QoderCLI/memory)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.