9. CLI 命令行参考

基础命令

Claude Code 的核心入口就是 claude 命令。下面是最常用的几种调用方式：

命令	描述	示例
claude	启动交互式会话	claude
claude "query"	带初始提示启动交互式会话	claude "explain this project"
claude -p "query"	打印响应后退出（非交互模式）	claude -p "explain this function"
cat file | claude -p "query"	处理管道输入	cat logs.txt | claude -p "explain"
claude -c	继续当前目录最近的对话	claude -c
claude -r "<session>" "query"	按 ID 或名称恢复会话	claude -r "auth-refactor" "Finish this PR"
claude update	更新到最新版本	claude update

最简单的就是直接打 claude，进入交互式会话。如果你想一进去就让 Claude 干活，可以带上初始提示。

其他常用子命令

除了 claude 本身，还有一些管理类子命令：

命令	用途
claude doctor	打印安装和配置诊断，不启动会话
claude mcp	配置 MCP 服务器
claude plugin	管理插件
claude agents	打开 agent view 监控后台会话
claude auth login	登录账户
claude auth logout	注销账户
claude auth status	查看认证状态
claude setup-token	为 CI 和脚本生成长期令牌
claude install [version]	安装或重新安装原生二进制文件

打印模式（-p）

-p（或 --print）是最重要的标志之一。它让 Claude Code 不进入交互式界面，而是直接打印响应然后退出。

claude -p "explain this function"

这看起来不起眼，但它是脚本化和自动化的基础。你可以把 Claude Code 嵌入到 shell 脚本、CI/CD 流水线、Makefile 里。

管道输入

-p 模式支持从 stdin 读取内容。你可以用管道把文件内容传给 Claude：

# 分析日志文件
cat logs.txt | claude -p "summarize the errors"

# 分析 git diff
git diff | claude -p "review this diff for bugs"

# 分析命令输出
kubectl get pods | claude -p "which pods are crashing?"

这种模式特别适合把 Claude Code 当成一个「智能管道过滤器」用——前一步的输出，经过 Claude 分析，变成下一步的输入。

限制轮次和预算

在脚本场景下，你可能想限制 Claude 的执行范围，防止它跑太久：

# 最多执行 3 轮
claude -p --max-turns 3 "fix the type errors"

# 最多花费 5 美元
claude -p --max-budget-usd 5.00 "refactor the auth module"

--max-turns 限制代理轮次，达到上限会报错退出。--max-budget-usd 限制 API 调用花费，达到金额就停。

输出格式

-p 模式支持三种输出格式，用 --output-format 指定：

格式	用途	示例
text	纯文本（默认）	claude -p "query"
json	JSON 对象，便于编程解析	claude -p "query" --output-format json
stream-json	流式 JSON，逐条输出	claude -p --output-format stream-json "query"

json 格式在脚本里最实用，可以直接用 jq 等工具解析：

# 提取 Claude 的回复文本
claude -p "list all TODO comments" --output-format json | jq '.result'

# 流式输出，实时看到每一步
claude -p --output-format stream-json --verbose "explain the architecture"

结构化输出

如果你需要 Claude 返回符合特定 schema 的 JSON，可以用 --json-schema：

claude -p --json-schema '{
  "type": "object",
  "properties": {
    "bugs": {"type": "array", "items": {"type": "string"}},
    "severity": {"type": "string", "enum": ["low", "medium", "high"]}
  }
}' "analyze this code for bugs"

Claude 会返回符合你定义的 JSON Schema 的结构化数据，方便后续程序处理。

常用标志分类

Claude Code 有大量命令行标志。这里按用途分类整理最常用的。

会话控制

标志	描述
--continue, -c	加载当前目录最近的对话
--resume, -r	按 ID 或名称恢复会话
--fork-session	恢复时创建新会话 ID
--session-id	指定会话 ID（UUID）
--name, -n	为会话设置显示名称
--no-session-persistence	不保存会话到磁盘

# 继续上次的对话
claude -c

# 恢复指定会话
claude -r "auth-refactor"

# 给会话起个名字，方便后续找回
claude -n "feature-auth-work"

模型与推理

标志	描述
--model	指定模型（支持别名 sonnet/opus/haiku）
--effort	设置推理工作量（low/medium/high/xhigh/max）
--fallback-model	主模型不可用时自动切换

# 用 Opus 处理复杂任务
claude --model opus "refactor the entire auth system"

# 用低工作量跑简单任务，省时间
claude --effort low -p "what does this function do"

# 主模型过载时自动降级到 Sonnet
claude --fallback-model sonnet,haiku "fix the bug"

权限与安全

标志	描述
--permission-mode	指定权限模式启动
--allowedTools	免权限提示的工具
--disallowedTools	禁用的工具
--dangerously-skip-permissions	跳过所有权限提示
--tools	限制可用工具范围

# 以计划模式启动
claude --permission-mode plan

# 只允许读取和 git 查看操作
claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"

# 限制只用 Bash、Edit、Read 三个工具
claude --tools "Bash,Edit,Read"

上下文与配置

标志	描述
--add-dir	添加额外工作目录
--settings	加载自定义 JSON 配置
--setting-sources	指定加载的设置源
--append-system-prompt	追加内容到默认系统提示
--system-prompt	替换整个系统提示

# 添加额外目录
claude --add-dir ../apps ../lib

# 追加系统提示
claude --append-system-prompt "Always use TypeScript"

# 加载自定义配置
claude --settings ./settings.json

并行与后台

标志	描述
--bg, --background	作为后台代理启动
--worktree, -w	在隔离的 git worktree 中启动
--exec	运行 shell 命令作为后台作业

# 后台调查一个 flaky test
claude --bg "investigate the flaky test"

# 在隔离 worktree 里开发新功能
claude -w feature-auth

# 后台运行测试
claude --bg --exec 'pytest -x'

调试与诊断

标志	描述
--debug	启用调试模式
--debug-file	调试日志写入指定文件
--verbose	详细日志输出
--safe-mode	禁用所有自定义，排查配置问题
--bare	最小模式，跳过所有自动发现

# 调试 API 和 MCP 问题
claude --debug "api,mcp"

# 安全模式启动，排除自定义干扰
claude --safe-mode

# 最小模式，脚本化调用更快
claude --bare -p "query"

--safe-mode 和 --bare 容易搞混：

系统提示自定义

Claude Code 提供四个标志来控制系统提示，全部在交互和非交互模式下都有效：

标志	行为	适用场景
--system-prompt	替换整个默认提示	完全自定义 Claude 身份
--system-prompt-file	从文件加载并替换	团队共享提示模板
--append-system-prompt	追加到默认提示	保留默认功能，加额外规则
--append-system-prompt-file	从文件追加	批量加载额外规则

# 追加：保留默认行为，加上 TypeScript 要求
claude --append-system-prompt "Always use TypeScript"

# 替换：完全自定义身份
claude --system-prompt "You are a Python expert"

# 从文件加载团队共享提示
claude --system-prompt-file ./prompts/review.txt

脚本化使用模式

把上面这些标志组合起来，就能在脚本里灵活使用 Claude Code。

模式一：一次性查询

# 简单问答
claude -p "what does this project do?"

# 带模型和输出格式
claude -p --model sonnet --output-format json "list all TODOs" | jq '.result'

模式二：管道处理

# 分析 git diff
git diff main..feature | claude -p "review this diff for bugs"

# 分析错误日志
cat error.log | claude -p "what's causing these errors?"

# 分析命令输出
npm test 2>&1 | claude -p "which tests failed and why?"

模式三：CI/CD 集成

# 用长期令牌认证
claude auth login --email you@example.com

# 在 CI 里跑代码审查
claude -p --output-format json \
  --max-turns 5 \
  --max-budget-usd 2.00 \
  "review the changes in this PR" | jq '.result'

# 用结构化输出
claude -p --json-schema '{
  "type": "object",
  "properties": {
    "approved": {"type": "boolean"},
    "issues": {"type": "array", "items": {"type": "string"}}
  }
}' "check if this code is safe to merge"

模式四：后台任务

# 后台跑一个调查任务
claude --bg "investigate the flaky test in CI"

# 查看后台会话
claude agents

# 查看某个会话的输出
claude logs <session-id>

标志组合速查

日常最常用的标志组合：

# 交互模式 + 指定模型
claude --model opus

# 打印模式 + JSON 输出
claude -p --output-format json "query"

# 打印模式 + 继续上次
claude -c -p "check for type errors"

# 后台 + worktree
claude --bg -w feature-auth "implement the auth module"

# 安全模式排查问题
claude --safe-mode

# 裸模式加速脚本
claude --bare -p "query"