# 34 · CLI 参考手册：命令与全部标志

> 📚 **系列导航**：上一篇 [33 钩子（Hooks）](33-hooks.md) 教你在固定事件上自动扣扳机、给 Claude 装上护栏。这一篇回到最朴素的地方——**你在终端敲的那一行 `claude`，到底能跟多少花样**。命令、标志、管道、退出码，一篇查完，配一张随时能翻的对照表。

「你这 `claude` 后面还能跟参数？我一直就光秃秃敲一个 `claude` 进去啊。」

「能啊，多了去了。让脚本跑个 `claude -p '总结这个 PR'`，结果直接吐到文件里，根本没进交互界面。」

「等下——`-p` 是啥？`claude --help` 翻了半天没看全。」

这段对话挺常见。很多人用 Claude Code 小半年，**一直只会光敲一个 `claude` 进交互模式**，根本不知道这命令背后还挂着几十个标志。这也怪不得谁——官方文档自己都写了一句话：`claude --help` **不会列出每个标志**。你光靠 `--help` 摸，注定漏一大片。

说白了，前面三十几篇咱们一直在「交互模式」里转：进去、聊天、它干活。**但 `claude` 本质是个命令行工具**，命令行工具的玩法远不止「打开一个界面」——它能接管道、能塞进脚本、能按退出码判断成败。今天这一篇就是那张「说明书」：把 `claude` 的命令、标志、管道用法、退出码一次摊开，**以后想查哪条直接翻表**。

**看完这一篇，你会拿到：**

- `claude` 的核心命令清单：启动、带初始提示、管道、继续 / 恢复会话、更新、登录，各干啥
- 最常用的一批标志（`-p` / `--model` / `-c` / `--resume` / `--permission-mode` / `--add-dir` 等）逐个讲清，配一张完整对照表
- headless（无头）与管道用法：怎么把 Claude 塞进脚本、当 linter、接 `jq` 处理输出
- 退出码怎么读：脚本里怎么靠它判断「成了还是没成」
- 一套能照着走完的 headless 完整链路：裸调用、管道喂料、结构化输出、退出码判断

---

## 01 先分清两个词：命令 vs 标志

动手翻表之前，先把两个最容易混的词钉死。**你在终端敲的一整行，拆开看就两样东西：命令（command）和标志（flag）。**

**类比：寄快递填单子。** `claude` 是「寄件」这个动作本身；后面跟的 `update`、`mcp` 这种是**子动作**（命令），告诉系统你今天不是寄普通件、是要「更新」或「配 MCP」；再后面那些 `-p`、`--model` 是单子上的**勾选框**（标志），微调这趟怎么寄——加急吗？保价吗？用哪个模型送？动作选一个，勾选框可以勾一堆。

落到具体：

```bash
claude update
claude -p "解释这个函数" --model sonnet
```

- 第一行：`claude` 是程序，`update` 是**命令**（一个子动作，跑完就退出）。
- 第二行：`claude` 后面没跟命令，直接进会话逻辑；`-p` 和 `--model` 都是**标志**，`-p` 后面的 `"解释这个函数"` 是这趟的初始提示。

这俩为啥要分清？**因为它们在文档里是分两张表列的，查的时候你得知道自己要查哪张。** 想知道「怎么更新 / 怎么登录 / 怎么配 MCP」——查命令表；想知道「怎么换模型 / 怎么不进交互直接出结果 / 怎么让它先别问权限」——查标志表。

还有个贴心细节值得先记：**敲错命令它会提示你**。官方原文说得很清楚——

> 如果您输入错误的子命令，Claude Code 会建议最接近的匹配项并退出而不启动会话。例如，`claude udpate` 会打印 `Did you mean claude update?`。

手快打错 `claude udpate` 是常事，每次它都老老实实问你「是不是想敲 `claude update`」，**不会傻乎乎拿错字去启动一个会话**。这点小体贴，省了不少「咦怎么没反应」的困惑。

> 💡 一句话总结：一行命令拆两样——**命令是子动作（`update`、`mcp`，跑完退出），标志是勾选框（`-p`、`--model`，微调这趟怎么跑）**；查文档先想清自己要查哪张表。

---

## 02 核心命令：启动会话的那几种姿势

先看命令。日常你真正会敲的就那么几条，我按「用途」分三组讲，每组配官方给的标准写法。

### 第一组：启动会话（最常用）

这组是你 90% 时间在用的：

```bash
# 1. 光秃秃启动，进交互模式
claude

# 2. 带一句初始提示启动（进去后它先回答这句）
claude "解释这个项目"

# 3. 不进交互、直接出结果就退出（headless / 打印模式）
claude -p "解释这个函数"
```

前两条你早就熟了。**第三条 `claude -p` 是这篇要重点讲的「另一种活法」**——它不打开那个聊天界面，直接把答案打印到终端然后退出，**专门给脚本和管道用**。第 04 节细讲。

### 第二组：接着上次聊（别让它失忆）

还记得第 19 篇说过的吗——**每开一个新会话，Claude 就是个「失忆的新实习生」**，上回聊到哪它全忘了。这两条命令就是治失忆的：

```bash
# 继续「当前目录」最近的那次对话
claude -c
# （--continue 是它的全称，-c 是简写）

# 按 ID 或名字恢复「某一次特定」的对话
claude -r "auth-refactor" "把这个 PR 收尾"
# （--resume 是全称，-r 是简写）
```

**两者的区别就一个词：「最近」还是「指定」。**

- `-c`（`--continue`）：只认「**当前目录里最近**那一次」，不用你记 ID，最省事。
- `-r`（`--resume`）：**点名要哪一次**——给会话 ID 或你之前用 `--name` 起的名字；不给的话，会弹一个交互式列表让你挑。

**类比：跟同事接着聊。** `-c` 是「咱接着刚才那事说」——默认就是最近那档子事，不用解释是哪件；`-r` 是「上周三那个关于登录重构的事儿，咱继续」——你得明确点出是哪一桩，对方才翻得到那段记忆。

一个顺手的习惯：**手头就一条线在推进时用 `-c`，省得记名字**；同时开了好几摊活儿（这个查 bug、那个写测试），才用 `-r` 点名恢复——前提是启动时用 `--name`（简写 `-n`）给每摊起了名，不然一堆 UUID 也认不出哪个是哪个。一套完整流程长这样：

```bash
# 启动时起个好认的名字
claude -n "login-refactor"

# 几天后回来，按名字直接恢复这一摊
claude -r "login-refactor"
```

官方对 `--name` 的说明很直白——它设置的显示名会出现在 `/resume` 列表和终端标题里，**之后就能用 `claude --resume <名字>` 恢复**。同时推三四个任务时，全靠这个名字认人，比对着一串 `550e8400-...` 的 UUID 强太多了。

还有个组合值得单独点一下：**`-c` 和 `-p` 能叠用**。`claude -c -p "查一下有没有类型错误"` 的意思是「**接着最近那次对话，但这次走 headless、出结果就退**」——它带着上次的上下文，却不进交互界面。脚本里想「分几步推进同一个任务、每步自动跑」时，这个组合特别顺手（第 04 节那个连续 `--continue` 的例子就是这么串的）。

### 第三组：维护与账户

剩下这组不常敲，但你得知道它们在：

```bash
# 更新到最新版
claude update

# 安装 / 重装本机二进制（可指定版本：2.1.118 / stable / latest）
claude install stable

# 登录 Anthropic 账户
claude auth login

# 查登录状态（已登录退出码 0，未登录退出码 1）
claude auth status
```

`claude install` 那个能跟版本号的细节，关键时刻很救命：官方说它**接受 `2.1.118` 这种具体版本号，也接受 `stable`、`latest`**。设想这样一种情况——某个新版本更新后某个行为变了不合用，用 `claude install 2.1.x` **回退钉死在上一个稳定版**，等问题修了再放开，比干等着舒服多了。

`claude auth status` 那句「**已登录退出码 0、未登录退出码 1**」先记着，第 05 节讲退出码时还会回来用它——这是脚本里判断「当前到底登没登录」的标准招。

> 这几条都需要联网。国内访问 Anthropic 账户体系（登录、更新拉包）如果不通，先开「魔法上网」再敲。

> 💡 一句话总结：命令分三组记——**启动会话（`claude` / `claude "提示"` / `claude -p`）、接着上次聊（`-c` 认最近、`-r` 点名恢复）、维护账户（`update` / `install` / `auth`）**；`-c` 和 `-r` 是治「会话失忆」的两味药。

---

## 03 最常用的一批标志：逐个讲清

命令认完了，重头戏是标志。**标志几十个，但你日常真正高频用的就七八个**——我先把这几个讲透，再给你整张表兜底（第 06 节附完整对照表，那是用来「查」的，这节是用来「懂」的）。

### `-p` / `--print`：不进交互，直接出结果

最重要的一个，没有之一。**加上 `-p`，Claude 就不打开聊天界面了——它读你的提示、干活、把结果打印出来、退出，整个过程没有人盯着。**

```bash
claude -p "这个项目的 auth 模块是干啥的"
```

它是 headless（无头，指没有交互界面、纯命令行跑）模式的开关，也是后面所有「塞进脚本」「接管道」玩法的地基。第 04 节专门展开。

### `--model`：这趟用哪个模型

临时指定这一趟会话用哪个模型，**覆盖掉你设置里的默认模型**：

```bash
claude --model sonnet
claude --model opus
claude --model claude-sonnet-4-6   # 也可以写完整名字
```

可以用别名（`sonnet`、`opus` 指向各自最新款），也可以写完整模型名。模型怎么选、各档什么定位，第 05 篇讲过，这里只管「怎么在命令行临时切」。

### `--permission-mode`：这趟从哪种权限模式开

直接决定「Claude 这趟动手前问不问你」。还记得第 20 篇那根「权限缰绳」吗——这个标志就是在启动那一刻把缰绳松紧定好：

```bash
claude --permission-mode plan
```

官方给的可选值有这几个：

> 接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆盖设置文件中的 `defaultMode`。

简单说：`plan`（只规划不动手）、`acceptEdits`（自动批准改文件）、`bypassPermissions`（全放行、慎用）这几个最常用。**这些模式各自啥脾气，下一篇（第 35 篇）专门拆**，这里你只要知道「用这个标志能在启动时一步到位选好模式」。

### `--dangerously-skip-permissions`：那个名字带 dangerous 的开关

这个标志单拎出来说，**因为新手最爱问、也最容易乱用**。它的作用就是跳过所有权限提示——官方说得明明白白，它**等同于 `--permission-mode bypassPermissions`**：

```bash
claude --dangerously-skip-permissions
```

加上它，Claude 改文件、跑命令一律不再停下来问你，闷头干到底。**名字里直接写了 `dangerously`（危险地），就是 Anthropic 在提醒你掂量**。第 20、21 篇反复强调过那根「权限缰绳」——这个开关相当于**把缰绳整个撒手**。

这里有条该守住的红线：**只在「明确隔离、坏了也无所谓」的环境里用它**——比如一次性的容器、玩具仓库、CI 里的临时沙箱。**在你真正的项目目录、尤其碰得到生产数据的地方，碰都别碰**。headless 批处理想少点权限提示，优先用 `--allowedTools` 精确放行几个工具，或者用 `--permission-mode acceptEdits` 只放开「改文件」——比一刀切全放行安全得多。

### `--add-dir`：让它多看一个目录

默认 Claude 只能读 / 改你启动时所在的那个目录。`--add-dir` 给它**额外开几个目录的访问权**：

```bash
claude --add-dir ../apps ../lib
```

典型场景：你的项目和它依赖的另一个库分在两个文件夹，想让 Claude 同时能动两边。**注意官方的一句提醒**——

> 授予文件访问权限；大多数 `.claude/` 配置不会从这些目录中发现。

也就是说：`--add-dir` 只给「**读写文件**」的权限，**不会**顺带把那个目录里的 CLAUDE.md、Skill 这些配置也加载进来。别指望加个目录就把人家那套配置也继承了。

### `--output-format`：结果按什么格式吐

只在 `-p` 打印模式下有意义，控制结果长什么样：

```bash
claude -p "总结这个项目" --output-format json
```

三个选项：`text`（默认，纯文本）、`json`（带会话 ID、成本等元数据的结构化结果）、`stream-json`（一行一个 JSON 事件，实时流式）。**脚本里想拿到「这趟花了多少钱」「会话 ID 是啥」，就得用 `json`**——第 04 节会演示拿它喂 `jq`。

### `--allowedTools` / `--disallowedTools`：白名单 / 黑名单

预先放行（或拒绝）某些工具，免得 headless 跑到一半卡在权限提示上（没人盯着的脚本一卡就废了）：

```bash
claude -p "跑测试并修掉失败" --allowedTools "Bash,Read,Edit"
```

`--allowedTools` 列出的工具**无需提示直接放行**；`--disallowedTools` 反过来拒绝。它俩用的是权限规则语法（详见第 20 篇），比如 `"Bash(git diff *)"` 只放行 `git diff` 开头的命令。

注意和 `--tools` 的区别——`--tools` 直接从模型上下文里删掉某个工具、让它完全用不了；`--allowedTools` 只是跳过权限提示，工具本身还在。

### 几个 headless 专用的「保险丝」

这几个只在 `-p` 模式下生效，但很实用，专门防脚本失控：

```bash
# 限制最多跑几轮，超了报错退出（默认无限制）
claude -p --max-turns 3 "查询"

# API 花费一旦超过这个金额就停（单位美元）
claude -p --max-budget-usd 5.00 "查询"
```

**`--max-turns` 这里藏着一个小坑**：写自动化脚本时忘了加它，万一某次 Claude 陷进反复试错的循环，turn 数蹭蹭涨、费用也跟着涨，脚本没人盯就白白烧钱。稳妥的做法是固定给批量脚本都加上 `--max-turns`，**相当于给它定个「最多折腾几个回合」的硬上限**，超了就报错退出，反而踏实。

> 💡 一句话总结：高频标志记这几个——**`-p` 出结果不进交互、`--model` 切模型、`--permission-mode` 定权限松紧、`--add-dir` 多看目录、`--output-format json` 拿结构化结果、`--allowedTools` 预放行工具**；脚本怕失控就加 `--max-turns` / `--max-budget-usd` 当保险丝。

---

## 04 headless 与管道：把 Claude 塞进命令行

这一节是 `claude -p` 真正发光的地方。**前面几十篇 Claude 都是「你打开一个窗口跟它聊」，这一节它变成「命令行里一个能接管道的零件」**——可以被别的命令喂数据，也可以把结果吐给下一个命令。

**类比：流水线上的一个工位。** 交互模式像你坐在工作台前一件件手工做；headless 模式则是把 Claude 焊到一条流水线上——**上一道工序（比如 `cat`、`git diff`）把料送进来，Claude 加工完，结果直接流到下一道（比如写进文件、喂给 `jq`）**。你不用守在旁边，整条线自己跑。

### 管道：喂数据进去

非交互模式会读 stdin（标准输入），所以你能像对待任何命令行工具一样，**用 `|` 把数据管道喂给它**：

```bash
cat build-error.txt | claude -p '简明解释这个构建错误的根本原因' > output.txt
```

这条命令干了三件事：`cat` 把日志内容吐出来 → 管道喂给 `claude -p` → 它解释完，`>` 把结果写进 `output.txt`。**全程没进任何界面，适合塞进任何自动化流程。**

> 这里有个官方明确的上限值得记：从 v2.1.128 起，**管道喂进去的内容上限是 10MB**，超了 Claude Code 会报清晰错误并以非零状态退出。要处理更大的输入，把内容写进文件、在提示里引用文件路径，别硬管道。

### 当项目专属 linter 用

把 headless 调用包进脚本，Claude 就成了你项目的「专属审查员」。官方给的这个 `package.json` 例子很典型——把对 `main` 的 diff 喂给 Claude，让它挑拼写错误：

```json
{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}
```

之后 `npm run lint:claude` 就能跑。**管道喂 diff 的好处**：Claude 不需要 Bash 权限去自己读 diff，料是你喂进去的。

### 接 `jq` 处理结构化输出

想在脚本里只取结果文本、或者抓会话 ID，就用 `--output-format json` 配 `jq`（一个命令行 JSON 处理工具）：

```bash
# 只取结果文本
claude -p "总结这个项目" --output-format json | jq -r '.result'
```

`json` 格式吐出来的是个带元数据的对象——结果文本在 `.result` 字段，会话 ID 在 `.session_id`，还有 `total_cost_usd` 这趟花了多少钱。**脚本要串起多轮对话，靠的就是先抓 `session_id` 再 `--resume`**：

```bash
session_id=$(claude -p "开始审查" --output-format json | jq -r '.session_id')
claude -p "继续那次审查" --resume "$session_id"
```

### 给这趟脚本调用安一个「临时身份」

headless 跑批处理时，常常想让 Claude 在这一趟里扮演某个特定角色——比如「你是安全工程师，专挑漏洞」。用 `--append-system-prompt` 把这条指令**追加到默认系统提示末尾**，官方这个例子把 PR 的 diff 喂给它做安全审查：

```bash
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
```

这里要分清两个标志，**别用错**：`--append-system-prompt` 是「**在默认提示后面追加**」，Claude 还保留它原本那套编程助手的本事和安全指令，你只是补一条额外要求；`--system-prompt` 则是「**整个替换掉**」默认提示——连工具用法、安全约束全没了，得你自己对剩下的一切负责。**九成场景你要的是 `append`（追加），不是 `system-prompt`（替换）**；只有当 Claude 那套「编程助手」的默认身份压根不适合你的任务时，才用替换。

### `--bare`：脚本里启动更快

还有一个专为脚本生的标志 `--bare`（裸模式）。官方原话：

> 最小模式：跳过 hooks、skills、plugins、MCP 服务器、自动内存和 CLAUDE.md 的自动发现，以便脚本化调用启动更快。

说白了，**普通 `claude -p` 会把交互会话那一整套上下文（你的 CLAUDE.md、装的 Skill、配的 MCP）全加载一遍**；`--bare` 把这些全跳过，只留 Bash、读文件、改文件三样基本能力，**启动快、且在每台机器上结果一致**（不会被某人 `~/.claude` 里的私货影响）。CI 和脚本里特别有用。官方文档也明确说了：`--bare` 将在未来版本中成为 `-p` 的默认值，现在就养成这个习惯挺值当的。

交互模式和 headless 模式的差别，并排看最清楚：

| 维度 | 交互模式（`claude`） | headless 模式（`claude -p`） |
|------|---------------------|------------------------------|
| 有没有聊天界面 | ✅ 有，你来回打字 | ❌ 没有，出结果就退 |
| 有无人值守 | ✅ 你坐在前面 | ❌ 无人，脚本自动跑 |
| 能接管道吗 | ❌ 不能 | ✅ 能，读 stdin、可重定向 |
| 权限怎么办 | 动手前停下来问你 | 靠 `--allowedTools` / `--permission-mode` 预先定好 |
| 典型场景 | 日常开发、对话式干活 | CI、批处理、当 linter、塞进脚本 |

> 💡 一句话总结：`claude -p` 把 Claude 变成命令行里能接管道的零件——**`cat ... | claude -p ... > out.txt` 串流水线、`--output-format json` 配 `jq` 抓字段、`--bare` 让脚本启动更快更干净**；没人盯的活儿，权限一定要用标志预先放好。

---

## 05 退出码：脚本怎么知道「成了还是没成」

这一节短，但写脚本的人**绕不开**。

**类比：考试的「及格 / 不及格」一个数字。** 命令行世界里，每条命令跑完都会留下一个「退出码（exit code）」——一个数字，**`0` 代表成功，非 `0` 代表出了某种问题**。它不是给你看的，是给「上一层脚本」看的：脚本靠这个数字判断「这步成了没，要不要继续往下走」。

你在终端可以这样查刚跑完那条命令的退出码：

```bash
claude auth status
echo $?
```

`echo $?` 打印的就是上一条命令的退出码（`$?` 是 shell 里存「上条命令退出码」的变量）。

官方文档里明确给了退出码的命令，挑几条你用得上的：

| 命令 / 情况 | 退出码 | 含义 |
|------------|--------|------|
| `claude auth status` 已登录 | `0` | 当前已登录 |
| `claude auth status` 未登录 | `1` | 当前未登录 |
| `claude -p --max-turns N` 达到上限 | 非 `0`（报错） | 超了轮数限制，以错误退出 |
| 管道 stdin 超过 10MB | 非 `0` | 输入太大，报清晰错误并非零退出 |
| `claude daemon status` supervisor 没在跑 | `1` | 后台会话管理进程未运行 |

**这玩意儿实际怎么用？** 比如 CI 里想「先确认登录了，没登录就直接让流水线失败」，就靠 `claude auth status` 的退出码：

```bash
# 没登录（退出码非 0）就报错退出，不往下跑
claude auth status || { echo "未登录，终止"; exit 1; }
```

`||` 的意思是「**前面那条要是失败了（退出码非 0），就执行后面这段**」。在一个每天定时跑的脚本里就可以这么干——开头先 `claude auth status` 探一下，**令牌要是过期了，脚本立刻停在这儿报警，而不是傻乎乎往下跑到一半才发现没登录**，白白浪费半天。

> 记住这条朴素的约定就够了：**`0` = 成功往下走，非 `0` = 出事了该停**。Claude Code 各个命令都遵守它，你写脚本判断成败时认准这个数字。

> 💡 一句话总结：退出码是「给脚本看的成绩单」——**`0` 成功、非 `0` 出问题**；`claude auth status` 用 `0`/`1` 报登没登录，`--max-turns` 超限和管道超 10MB 都以非零退出，脚本里靠 `$?` 或 `||` 接住它。

---

## 06 标志全表：用来「查」的那一页

前面讲透了高频的，这一节是兜底——**把官方文档里你日常碰得到的标志整理成一张表，专门拿来「查」**。标志几十个，没必要背，存着随时翻就行。

> 提醒一句官方原话：**`claude --help` 不会列出每个标志**，所以某个标志在 `--help` 里没出现，不代表它不能用——以官方 CLI 参考文档为准。

我按「干啥用的」分类列，方便你按需求找：

**启动与会话**

| 标志 | 简写 | 干啥 |
|------|------|------|
| `--print` | `-p` | 不进交互、打印结果就退出（headless 地基） |
| `--continue` | `-c` | 继续当前目录最近的对话 |
| `--resume` | `-r` | 按 ID / 名字恢复特定会话，或弹列表选 |
| `--name` | `-n` | 给会话起显示名，方便之后 `--resume <名字>` |
| `--fork-session` | — | 恢复时新建会话 ID，不复用原来的（配 `-r`/`-c`） |
| `--session-id` | — | 指定一个会话 ID（必须是合法 UUID） |

**模型与权限**

| 标志 | 干啥 |
|------|------|
| `--model` | 这趟用哪个模型（别名 `sonnet`/`opus` 或完整名），覆盖默认 |
| `--fallback-model` | 默认模型过载 / 不可用时自动回退到指定模型（`-p` 和后台会话生效，交互被忽略） |
| `--permission-mode` | 从哪种权限模式开（`default`/`acceptEdits`/`plan`/`auto`/`dontAsk`/`bypassPermissions`） |
| `--allowedTools` | 无需提示直接放行的工具 |
| `--disallowedTools` | 拒绝规则 |
| `--dangerously-skip-permissions` | 跳过所有权限提示（等同 `--permission-mode bypassPermissions`，慎用） |

**目录与配置**

| 标志 | 干啥 |
|------|------|
| `--add-dir` | 额外给几个目录的读写权（只给文件访问，不加载那里的配置） |
| `--settings` | 指定 settings JSON 文件或内联 JSON，覆盖本会话同名键 |
| `--setting-sources` | 加载哪些设置源（`user`/`project`/`local`） |
| `--mcp-config` | 从 JSON 文件 / 字符串加载 MCP server |
| `--bare` | 最小模式：跳过 hooks/skills/plugins/MCP/内存/CLAUDE.md 自动发现，启动更快 |

**headless 输出与控制（多数仅 `-p` 生效）**

| 标志 | 干啥 |
|------|------|
| `--output-format` | 输出格式：`text`（默认）/ `json` / `stream-json` |
| `--input-format` | 输入格式：`text` / `stream-json` |
| `--max-turns` | 限制最多几轮，超了报错退出（默认无限制） |
| `--max-budget-usd` | API 花费超过这个美元数就停 |
| `--verbose` | 详细日志，显示完整逐轮输出 |
| `--append-system-prompt` | 在默认系统提示末尾追加自定义文本 |
| `--system-prompt` | 用自定义文本替换整个默认系统提示 |

**杂项**

| 标志 | 简写 | 干啥 |
|------|------|------|
| `--version` | `-v` | 输出版本号 |
| `--ide` | — | 启动时若恰好有一个可用 IDE 就自动连接 |
| `--debug` | — | 开调试模式，可按类别过滤（如 `"api,mcp"`） |

这张表覆盖了你前期会用到的绝大多数标志。**真要查全集（还有几十个偏门的，比如后台会话、agent team、remote control 相关），去翻官方 CLI 参考页**——它才是那本「全集说明书」，本节是「常用速查」。

> 💡 一句话总结：标志按「启动会话 / 模型权限 / 目录配置 / headless 输出 / 杂项」分类查最快；**`--help` 不全，以官方 CLI 参考为准**；这张表管常用，偏门的去官方全集翻。

---

## 07 动手：把 `claude -p` 接进命令行管道

光看表不算会，得真把 headless 跑一遍。下面这套**全在终端里完成，不进任何交互界面**——亲手体会「Claude 当命令行零件」是什么感觉。用最小示例，不依赖你已有的复杂项目。

> 这几步需要联网，且会消耗一点额度（每次 `-p` 调用都是一次真实请求）。国内若 API 不通，先开「魔法上网」。

**第一步：最朴素的一次 `-p` 调用**

随便找个目录，在终端敲（不是在 `claude` 会话里）：

```bash
claude -p "用一句话说明 git rebase 和 git merge 的核心区别"
```

**预期**：终端**直接打印出一句回答然后退出**，全程没有那个聊天界面弹出来。看到结果一闪而过、提示符又回来了 = headless 模式跑通了。

**第二步：把它接进管道，喂数据进去**

造一个小文件当「输入料」，管道喂给 Claude：

```bash
printf 'def add(a, b):\n    return a - b\n' > buggy.py
cat buggy.py | claude -p "这段代码有个 bug，一句话指出来"
```

**预期**：Claude 读到管道喂进去的代码，回一句类似「函数名是 `add` 但实际做的是减法（`a - b`）」。**看到它能就「你喂进去的内容」作答 = 管道通了**——它根本没用工具去读文件，料是 `cat` 送进它嘴里的。

**第三步：要结构化输出，接 `jq` 取字段**

```bash
claude -p "用一句话介绍 Python 是什么语言" --output-format json
```

**预期**：这次吐出来的不是纯文本，而是**一大坨 JSON**，里面有 `result`（结果文本）、`session_id`、`total_cost_usd` 等字段。如果你机器上装了 `jq`，再试这条只取结果：

```bash
claude -p "用一句话介绍 Python" --output-format json | jq -r '.result'
```

**预期**：这回只打印出那句干净的结果文本，外层 JSON 被 `jq` 剥掉了。**这就是脚本里「只要那句答案、不要一堆元数据」的标准拿法。**

**第四步：用退出码判断成败**

```bash
claude auth status
echo $?
```

**预期**：如果你已登录，`echo $?` 打印 `0`；没登录则打印 `1`。**这个数字就是脚本判断「该不该往下走」的依据**——第 05 节那条 `claude auth status || ...` 就是接住它。

跑通这四步，你就把「**单次调用 → 管道喂料 → 结构化输出接 `jq` → 退出码判断**」这条 headless 完整链路亲手走了一遍。**以后想把 Claude 塞进任何脚本、CI、定时任务，本质都是这套零件的排列组合。**

> 💡 一句话总结：动手四步把 headless 走通——**裸 `-p` 出结果、管道 `cat | claude -p` 喂料、`--output-format json | jq` 取字段、`auth status` + `$?` 判成败**；这四块拼起来就是一切自动化的地基。

---

## 08 小结

这一篇把你天天敲的那行 `claude` 彻底摊开了——**从「只会光敲一个 `claude` 进界面」，升级到「命令、标志、管道、退出码全门儿清」**。

把核心串起来回顾：

| 你想干啥 | 用什么 | 关键点 |
|---------|--------|--------|
| 分清命令和标志 | 命令是子动作、标志是勾选框 | `update`/`mcp` 是命令，`-p`/`--model` 是标志 |
| 启动 / 续聊 | `claude` / `-c` / `-r` | `-c` 认最近、`-r` 点名恢复，治会话失忆 |
| 不进交互直接出结果 | `-p`（`--print`） | headless 地基，给脚本和管道用 |
| 临时切模型 / 定权限 | `--model` / `--permission-mode` | 覆盖默认设置，只管这一趟 |
| 把它塞进命令行 | 管道 + `--output-format json` + `jq` | `cat ... \| claude -p ... \| jq` 串流水线 |
| 脚本判断成败 | 退出码 | `0` 成功、非 `0` 出事，靠 `$?` 或 `\|\|` 接住 |
| 查某个标志 | 第 06 节速查表 / 官方全集 | `--help` 不全，以官方 CLI 参考为准 |

**你现在应该能：** 看着任意一行 `claude xxx --yyy` 都拆得清「哪个是命令、哪个是标志、各干啥」；想续上之前的对话知道该用 `-c` 还是 `-r`；要把 Claude 塞进脚本时，会用 `-p` 配管道和 `--output-format json`，还会拿退出码判断这步成没成；遇到没见过的标志，知道去哪张表查、也知道 `--help` 靠不住得翻官方全集。**这套命令行功夫，是你把 Claude Code 从「一个聊天窗口」真正变成「开发工作流里一个可编排零件」的分水岭。**

开头那位光敲 `claude` 的人，学会 `-p` 加管道之后，就能把每天手动跑的几个检查全写进脚本——**那感觉，像是突然把 Claude 从「副驾」请到了「流水线」上**。这一篇就是想让你也有这一刻。

---

下一篇 **35「控制与模式」**——这一篇里我反复提到 `--permission-mode` 能选 `plan`、`acceptEdits`、`bypassPermissions` 这几档，但**每一档具体是什么脾气、动手前问你几次、什么场景该切到哪档，我一直按下没展开**。下一篇就专门把这几种模式掰开揉碎，连同会话里怎么用快捷键随手切换一起讲透。想想看：同样让 Claude 改一堆文件，**「每改一个文件问你一次」和「闷头改完再给你看」，效率和安全感能差出十条街**——这中间的拿捏，下一篇见。
