05.3 CLI 命令与 Flag 速查

claude 命令行的全部子命令与高价值 flag，带实战注解。

读完你能做什么：脱离交互界面，从 shell 直接驱动 Claude Code，并把它嵌进脚本。

📌 版本提示：Claude Code 迭代很快，flag 会增删。claude --help 不会列出所有 flag（官方明确说明这一点）。以本文为地图，以 claude --help 和官方 CLI reference 为准。

---

一、核心子命令

1.1 启动与会话

claude                              # 启动交互式会话
claude "解释这个项目"                # 带初始提示词启动
claude -p "解释这个函数"            # 查询后立即退出（SDK/print 模式）
cat logs.txt | claude -p "分析"     # 处理管道输入
claude -c                           # 继续当前目录最近的会话
claude -c -p "检查类型错误"         # 非交互式继续
claude -r "auth-refactor" "完成 PR" # 按 ID 或名字恢复会话

1.2 维护

claude update                       # 更新到最新版
claude install stable               # 安装特定版本（stable/latest/2.1.118）
claude doctor                       # 只读安装诊断（不启动会话）
claude --version                    # 版本号

1.3 认证

claude auth login                   # 登录
claude auth login --console         # 走 Console（API 计费）
claude auth status                  # 认证状态（JSON）
claude auth logout                  # 登出
claude setup-token                  # 生成 CI 用的长效 token

1.4 MCP 管理

claude mcp                          # MCP 配置入口
claude mcp add ...                  # 添加 server（详见 07.2）
claude mcp list                     # 列出所有 server
claude mcp login <name>             # 跑某个 server 的 OAuth 流程
claude mcp logout <name>            # 清除某 server 的凭据

1.5 后台会话与并行（进阶）

claude --bg "调查这个 flaky test"   # 启动后台会话，立即返回
claude agents                       # 打开 agent view，监控并行会话
claude agents --json                # 以 JSON 输出活跃会话（脚本用）
claude attach <id>                  # 把后台会话接管到当前终端
claude logs <id>                    # 打印后台会话的近期输出
claude stop <id>                    # 停止后台会话
claude respawn <id>                 # 重启后台会话（对话保留）
claude rm <id>                      # 从列表移除（transcript 仍保留）

详见 06.7 Worktrees 与并行开发。

1.6 插件

claude plugin install <name>@<marketplace>   # 安装插件
claude plugin ...                            # 其他子命令见 plugins-reference

见 10.1 Plugin 与 Marketplace。

---

二、高价值 Flag（按用途分组）

2.1 模型与推理

Flag	作用	示例
--model	指定模型	claude --model opus
--effort	推理投入 low/medium/high/xhigh/max	claude --effort high
--fallback-model	主模型不可用时降级链	claude --fallback-model sonnet,haiku

2.2 权限与安全

Flag	作用	示例
--permission-mode	起始权限模式	claude --permission-mode plan
--allowedTools	免批准的工具	--allowedTools "Bash(git log *)" "Read"
--disallowedTools	拒绝规则	--disallowedTools "mcp__*"
--tools	限制可用的内置工具	--tools "Bash,Edit,Read"
--dangerously-skip-permissions	跳过所有权限提示	⚠️ 仅在隔离环境用
--add-dir	增加可读写目录	claude --add-dir ../lib

权限模型详见 05.5。

2.3 系统提示词

Flag	作用
--system-prompt	替换整个默认提示词
--system-prompt-file	用文件替换
--append-system-prompt	追加到默认提示词
--append-system-prompt-file	追加文件内容

claude --append-system-prompt "所有代码用 TypeScript strict 模式"

详见 02.4。

2.4 Print / 脚本模式

Flag	作用	示例
-p, --print	非交互，打印后退出	claude -p "query"
--output-format	text/json/stream-json	claude -p "q" --output-format json
--input-format	text/stream-json
--json-schema	强制输出符合 JSON Schema	见下
--max-turns	限制代理轮数	claude -p --max-turns 5 "q"
--max-budget-usd	花费上限（含子代理）	claude -p --max-budget-usd 5.00 "q"
--verbose	完整逐轮输出

# 结构化输出：保证返回符合 schema 的 JSON
claude -p --json-schema '{
  "type": "object",
  "properties": {
    "bugs_found": {"type": "integer"},
    "files": {"type": "array", "items": {"type": "string"}}
  },
  "required": ["bugs_found", "files"]
}' "扫描 src 目录的空指针风险"

详见 06.6 Headless 与 CI 集成。

2.5 会话管理

Flag	作用
-c, --continue	继续最近的会话
-r, --resume	恢复指定会话（ID 或名字）
--fork-session	恢复时创建新会话 ID（不覆盖原会话）
-n, --name	给会话命名
--session-id	指定会话 UUID

2.6 配置控制

Flag	作用	使用场景
--mcp-config	从 JSON 加载 MCP
--strict-mcp-config	只用 --mcp-config 的 MCP，忽略其他	隔离项目 MCP
--settings	指定设置文件或内联 JSON
--setting-sources	加载哪些设置源 user,project,local
--safe-mode	禁用所有自定义（排障用）	配置坏了
--bare	跳过所有自动发现，启动最快	简单脚本

2.7 隔离与并行

Flag	作用	示例
-w, --worktree	在隔离的 git worktree 中启动	claude -w feature-auth
--bg, --background	作为后台代理启动	claude --bg "查 flaky test"
--agent	指定主会话代理	claude --agent my-agent
--agents	用 JSON 动态定义子代理	见 06.4

2.8 集成

Flag	作用
--chrome / --no-chrome	开/关 Chrome 浏览器集成
--ide	启动时自动连接 IDE
--remote-control, --rc	启用 Remote Control（从 claude.ai 控制）
--cloud	在 claude.ai 上创建 web 会话
--teleport	把 web 会话拉到本地终端

---

三、五个高频组合

3.1 安全的探索模式

# 只读探索一个陌生仓库，不怕它乱改
claude --permission-mode plan --model opus

3.2 隔离的实验

# 在独立 worktree 里试验，失败了删掉即可，主分支不受影响
claude -w experiment-new-arch

3.3 脚本化的批量处理

# 对每个文件跑同样的分析，输出结构化结果
for f in src/*.ts; do
  claude -p --bare --model haiku --output-format json \
    "分析 $f 的圈复杂度，输出 JSON: {\"file\":\"$f\",\"complexity\":N}"
done

3.4 受控的自动化

# 允许安全命令自动跑，危险的仍然问，且设花费上限
claude --max-budget-usd 3.00 \
  --allowedTools "Bash(npm test)" "Bash(npm run *)" "Read" "Edit" \
  --disallowedTools "Bash(rm *)" "Bash(git push *)"

3.5 CI 中的非交互运行

# CI 里跑一次代码审查，输出到文件
claude -p --max-turns 20 --output-format json \
  --append-system-prompt "只报告会导致生产问题的缺陷" \
  "审查本次 PR 的改动" > review.json

---

四、退出码（脚本必知）

场景	退出码
正常完成	0
claude auth status 已登录	0
claude auth status 未登录	1
--max-turns 达到上限	非 0（报错）
claude ultrareview 有发现	视结果 0 或 1

在脚本里据此判断：

if claude auth status > /dev/null 2>&1; then
  echo "已登录，继续"
else
  echo "未登录，跳过"; exit 1
fi

---

五、一个自检脚本

把你常用的组合固化成别名，放进 ~/.bashrc 或 ~/.zshrc：

# 只读探索
alias claude-explore='claude --permission-mode plan --model opus'

# 隔离实验
alias claude-lab='claude -w'

# 快速一次性问答（最省）
claude-ask() {
  claude --bare -p --model haiku "$*"
}

# 受控自动化
alias claude-auto='claude --allowedTools "Bash(npm test)" "Read" "Edit" --disallowedTools "Bash(rm *)" "Bash(git push *)"'

用法：

claude-ask "把这段 JSON 转成 YAML: $(cat data.json)"
claude-explore
claude-lab feature-payment

---

延伸阅读

• 05.4 斜杠命令速查 —— 会话内的命令
• 05.5 权限模型与安全边界
• 06.6 Headless 与 CI 集成
• 12.1 完整命令速查卡