ClaudeCodeCLI命令行接口精通Skill cli-reference

---

name: cli-reference description: Claude Code CLI 命令、标志、无头模式和自动化模式 allowed-tools: [Read]

CLI 参考

Claude Code 命令行接口的完整参考。

何时使用

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

核心命令

命令	描述	示例
claude	启动交互式 REPL	claude
claude "query"	带初始提示的 REPL	claude "解释这个项目"
claude -p "query"	无头模式（SDK）	claude -p "解释函数"
cat file | claude -p	处理管道内容	cat logs.txt | claude -p "解释"
claude -c	继续最近的对话	claude -c
claude -c -p "query"	通过 SDK 继续	claude -c -p "检查类型"
claude -r "id" "query"	恢复会话	claude -r "auth" "完成 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

无头模式（对代理关键）

标志	描述	示例
--print, -p	非交互式，执行后退出	claude -p "query"
--output-format	text、json、stream-json	claude -p --output-format json
--max-turns	限制代理轮次	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"

子代理定义（–agents 标志）

通过 JSON 内联定义自定义子代理：

claude --agents '{
  "code-reviewer": {
    "description": "专家代码审查员。代码更改后主动使用。",
    "prompt": "您是一名高级代码审查员。专注于代码质量和安全。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "调试专家，处理错误和测试失败。",
    "prompt": "您是一名专家调试员。分析错误并提供修复。"
  }
}'

代理字段

字段	必填	描述
description	是	何时调用此代理
prompt	是	行为系统提示
tools	否	允许的工具（如果省略则继承所有）
model	否	sonnet、haiku 或 claude-opus-4-5-20251101

关键洞察

当 Lead 使用 Task 工具时，自动从这些定义生成。无需手动生成。

系统提示自定义

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

使用 --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 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
# 换行分隔的 JSON 事件

结构化输出（模式验证）

claude -p "提取数据" \
  --output-format json \
  --json-schema '{"type":"object","properties":{...}}'

无头代理模式（关键）

正确的无头代理生成：

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 "运行测试并修复失败" \
  --dangerously-skip-permissions \
  --max-turns 50 \
  --output-format json | jq '.result'

管道输入

cat error.log | claude -p "查找根本原因"
gh pr diff | claude -p "审查安全性"

多轮会话

id=$(claude -p "开始任务" --output-format json | jq -r '.session_id')
claude -p "继续" --resume "$id"

流监控

claude -p "长任务" \
  --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 模式
#	添加到记忆
@	文件提及