> ## 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.

# 在脚本中运行 Qoder CLI

# 概述

Headless（非交互）模式让 Qoder CLI 在没有交互式界面的情况下运行——接收一个提示词，执行任务，把结果输出到标准输出，然后退出。它适合把 Qoder 嵌入 Shell 脚本、自动化流程和 CI/CD 流水线。

进入 Headless 模式的方式是加上 `--print`（简写 `-p`）：

```shell theme={null}
qodercli -p "解释这个代码仓库的架构"
```

由于没有人在旁边确认，Headless 模式下的权限需要预先配置好——任何原本需要弹窗确认的操作，在纯文本 Headless 模式下会被自动拒绝。相关说明见 [权限](https://docs.qoder.com/zh/cli/06-配置与安全/permissions.md)。

# 基本用法

把提示词作为参数传入，并加上 `-p`：

```shell theme={null}
qodercli -p "生成本次改动的提交信息"
```

也可以通过标准输入传入提示词：

```shell theme={null}
echo "总结昨天的所有代码变更" | qodercli -p
```

在脚本中捕获输出：

```shell theme={null}
result=$(qodercli -p "列出 src 目录下所有导出的函数")
echo "$result"
```

# 输出格式

用 `--output-format`（简写 `-o`）指定输出格式，默认是 `text`：

| 格式 | 说明 | 适用场景 |
| :- | :- | :- |
| `text` | 纯文本结果（默认） | 直接阅读、简单脚本 |
| `json` | 单个 JSON 对象，包含结果和元数据 | 需要程序化解析最终结果 |
| `stream-json` | 逐条输出的 JSON 消息流 | 需要实时消费中间过程 |

示例：

```shell theme={null}
# 纯文本（默认）
qodercli -p "解释 main.ts 的作用"

# JSON：便于脚本解析
qodercli -p "解释 main.ts 的作用" --output-format json

# Stream JSON：实时消费消息流
qodercli -p "重构 utils 模块" --output-format stream-json
```

输入格式可以用 `--input-format` 指定，支持 `text` 和 `stream-json`。使用 `stream-json` 输入时，可以通过标准输入持续发送结构化消息。

# 常用参数

Headless 模式下常配合以下参数使用：

| 参数 | 说明 |
| :- | :- |
| `-p, --print` | 打印响应并退出（非交互） |
| `-o, --output-format <format>` | 输出格式：text / json / stream-json |
| `--input-format <format>` | 输入格式：text / stream-json |
| `--max-turns <count>` | 限制单次查询的最大对话轮数 |
| `--permission-mode <mode>` | 设置权限模式 |
| `--allowed-tools <tool>` | 仅允许指定工具 |
| `--disallowed-tools <tool>` | 禁止指定工具 |
| `-m, --model <model>` | 指定模型 |
| `--session-id <id>` | 使用指定的会话 id |
| `-w, --cwd <dir>` | 启动前切换工作目录 |

完整参数见 CLI 启动参数参考。

# 权限控制

Headless 模式下没有交互式确认，因此需要通过权限参数预先决定哪些操作可以自动执行：

```shell theme={null}
# 文件编辑自动通过，Shell 命令仍被拒绝
qodercli -p "重构 utils 模块" --permission-mode accept_edits

# 只放行特定工具
qodercli -p "检查状态" --allowed-tools 'Read,Bash(git status)'

# 全部放行（仅限可信场景）
qodercli -p "执行数据库迁移" --yolo
```

* 在纯文本 Headless 模式下，任何"需要确认"的操作默认转为拒绝；若由宿主程序通过 stream-json 协议驱动（例如 Agent SDK），确认请求会转交宿主程序决策，见 [权限](https://docs.qoder.com/zh/cli/06-配置与安全/permissions.md) 中"不同运行环境下 `ask` 的消费方式"。
* 用 `--permission-mode accept_edits` 可自动批准工作目录内的安全文件编辑。
* 用 `--yolo`（等价于 `--permission-mode bypass_permissions`）跳过所有确认，**仅建议在完全可信的环境中使用**。

各权限模式的行为详见 [权限](https://docs.qoder.com/zh/cli/06-配置与安全/permissions.md)。

# CI/CD 示例

在流水线中，通常先通过环境变量完成认证，再以 Headless 模式运行：

```shell theme={null}
export QODER_PERSONAL_ACCESS_TOKEN="your_token"

qodercli -p "审查本次改动并列出潜在问题" \
  --output-format json \
  --permission-mode accept_edits \
  --max-turns 20
```

认证方式见 [登录与认证](https://docs.qoder.com/zh/cli/01-开始使用/auth.md)。把输出格式设为 `json`，便于流水线后续步骤解析 Qoder 的结果。


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