cli-reference

CLI 参考

Claude Code 命令行界面的完整参考。

适用场景

• “有哪些 CLI 标志可用？”
• “如何使用无头模式？”
• “在自动化/CI/CD 中使用 Claude”
• “输出格式选项”
• “通过 CLI 设置系统提示词”
• “如何正确启动 Agent？”

核心命令

命令	说明	示例
claude	启动交互式 REPL	claude
claude "query"	使用初始提示词启动 REPL	claude "explain this project"
claude -p "query"	无头模式（SDK）	claude -p "explain function"
cat file | claude -p	处理管道输入的内容	cat logs.txt | claude -p "explain"
claude -c	继续最近一次会话	claude -c
claude -c -p "query"	通过 SDK 继续会话	claude -c -p "check types"
claude -r "id" "query"	恢复会话	claude -r "auth" "finish PR"
claude update	更新版本	claude update
claude mcp	配置 MCP 服务	参阅 MCP 文档

会话控制

标志	说明	示例
--continue, -c	加载最近一次对话	claude --continue
--resume, -r	按 ID/名称恢复会话	claude --resume auth-refactor
--session-id	使用指定的 UUID	claude --session-id "550e8400-..."
--fork-session	恢复时创建新会话	claude --resume abc --fork-session

无头模式（对 Agent 至关重要）

标志	说明	示例
--print, -p	非交互模式，完成后退出	claude -p "query"
--output-format	text、json、stream-json	claude -p --output-format json
--max-turns	限制 Agent 交互轮数	claude -p --max-turns 100 "query"
--verbose	输出完整的逐轮信息	claude --verbose
--dangerously-skip-permissions	跳过权限提示	claude -p --dangerously-skip-permissions
--include-partial-messages	包含流式事件	claude -p --output-format stream-json --include-partial-messages
--input-format	输入格式（text/stream-json）	claude -p --input-format stream-json

工具控制

标志	说明	示例
--allowedTools	自动批准这些工具	"Bash(git log:*)" "Read"
--disallowedTools	禁止使用这些工具	"Bash(rm:*)" "Edit"
--tools	仅允许使用这些工具	--tools "Bash,Edit,Read"

子 Agent 定义（--agents 标志）

通过 JSON 内联定义自定义子 Agent：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors and provide fixes."
  }
}'

Agent 字段

字段	必填	说明
description	是	何时调用此 Agent
prompt	是	用于定义行为的系统提示词
tools	否	允许使用的工具（省略时继承全部工具）
model	否	sonnet、haiku 或 claude-opus-4-5-20251101

关键要点

Lead 使用 Task 工具时，会根据这些定义自动启动子 Agent。无需手动启动。

自定义系统提示词

标志	行为	模式
--system-prompt	替换整个提示词	交互式 + Print
--system-prompt-file	从文件替换提示词	仅 Print
--append-system-prompt	追加到默认提示词后（推荐）	交互式 + Print

大多数情况下使用 --append-system-prompt——这样可以保留 Claude Code 的功能。

模型选择

标志	说明	示例
--model	设置会话使用的模型	--model claude-sonnet-4-5
--fallback-model	默认模型过载时使用的备用模型	--fallback-model sonnet

别名：sonnet、opus、haiku

MCP 配置

标志	说明	示例
--mcp-config	从 JSON 加载 MCP 服务	--mcp-config ./mcp.json
--strict-mcp-config	仅使用这些 MCP 服务	--strict-mcp-config --mcp-config ./mcp.json

高级标志

标志	描述	示例
--add-dir	添加工作目录	--add-dir ../apps ../lib
--agent	指定会话的 Agent	--agent my-custom-agent
--permission-mode	以权限模式启动	--permission-mode plan
--permission-prompt-tool	用于权限的 MCP 工具	--permission-prompt-tool mcp_auth
--plugin-dir	从目录加载插件	--plugin-dir ./my-plugins
--settings	从文件/JSON 加载设置	--settings ./settings.json
--setting-sources	要加载的设置	--setting-sources user,project
--betas	Beta API 标头	--betas interleaved-thinking
--debug	启用调试模式	--debug "api,hooks"
--ide	自动连接到 IDE	--ide
--chrome	启用 Chrome 集成	--chrome
--no-chrome	为会话禁用 Chrome	--no-chrome
--enable-lsp-logging	详细的 LSP 调试日志	--enable-lsp-logging
--version, -v	输出版本	claude -v

输出格式

JSON（用于解析）

claude -p "query" --output-format json
# {"result": "...", "session_id": "...", "usage": {...}}

流式输出（用于实时监控）

claude -p "query" --output-format stream-json
# Newline-delimited JSON events

结构化输出（模式验证）

claude -p "Extract data" \
  --output-format json \
  --json-schema '{"type":"object","properties":{...}}'

无头 Agent 模式（重要）

正确启动无头 Agent：

claude -p "$TASK_PROMPT" \
  --session-id "$UUID" \
  --dangerously-skip-permissions \
  --max-turns 100 \
  --output-format stream-json \
  --agents '{...}' \
  --append-system-prompt "Context: ..."

缺少以下任何一项都会导致进程挂起：

• --session-id - 跟踪会话
• --dangerously-skip-permissions - 无头模式需要此项
• --max-turns - 防止无限循环

常见模式

CI/CD 自动化

claude -p "Run tests and fix failures" \
  --dangerously-skip-permissions \
  --max-turns 50 \
  --output-format json | jq '.result'

管道输入

cat error.log | claude -p "Find root cause"
gh pr diff | claude -p "Review for security"

多轮会话

id=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude -p "Continue" --resume "$id"

流式监控

claude -p "Long task" \
  --output-format stream-json \
  --include-partial-messages | while read -r line; do
    echo "$line" | jq '.type'
done

键盘快捷键（交互式）

快捷键	操作
Ctrl+C	取消当前操作
Ctrl+D	退出
Ctrl+R	反向搜索历史记录
Esc Esc	撤销更改
Shift+Tab	切换权限模式

快捷命令

前缀	操作
/	斜杠命令
!	Bash 模式
#	添加到记忆
@	文件提及