claude-howto/zh/10-cli

CLI 参考

概览

Claude Code 的 CLI（命令行接口）是与 Claude Code 交互的主要方式。它提供了强大的参数和命令，用于执行查询、管理会话、配置模型，并把 Claude 集成进你的开发工作流。

架构

graph TD
    A["用户终端"] -->|"claude [options] [query]"| B["Claude Code CLI"]
    B -->|Interactive| C["REPL 模式"]
    B -->|"--print"| D["打印模式（SDK）"]
    B -->|"--resume"| E["恢复会话"]
    C -->|Conversation| F["Claude API"]
    D -->|Single Query| F
    E -->|Load Context| F
    F -->|Response| G["输出"]
    G -->|text/json/stream-json| H["终端 / 管道"]

CLI 命令

命令	说明	示例
claude	启动交互式 REPL	claude
claude "query"	带初始提示启动 REPL	claude "解释这个项目"
claude -p "query"	打印模式，查询后退出	claude -p "解释这个函数"
cat file | claude -p "query"	处理通过管道传入的内容	cat logs.txt | claude -p "解释这些日志"
claude -c	继续最近一次会话	claude -c
claude -c -p "query"	在打印模式下继续会话	claude -c -p "检查类型错误"
claude -r "<session>" "query"	通过 ID 或名称恢复会话	claude -r "auth-refactor" "完成这个 PR"
claude update	更新到最新版本	claude update
claude mcp	配置 MCP servers	见 MCP 文档
claude mcp serve	将 Claude Code 作为 MCP server 运行	claude mcp serve
claude agents	列出所有已配置的 subagents	claude agents
claude auto-mode defaults	以 JSON 打印 auto mode 默认规则	claude auto-mode defaults
claude remote-control	启动远程控制服务	claude remote-control
claude plugin	管理插件（安装、启用、禁用）	claude plugin install my-plugin
claude auth login	登录（支持 --email、--sso）	claude auth login --email user@example.com
claude auth logout	注销当前账号	claude auth logout
claude auth status	检查登录状态（已登录返回 0，否则返回 1）	claude auth status

核心标志

参数	说明	示例
-p, --print	不进入交互式模式，直接输出结果	claude -p "query"
-c, --continue	加载最近一次会话	claude --continue
-r, --resume	按 ID 或名称恢复指定会话	claude --resume auth-refactor
-v, --version	输出版本号	claude -v
-w, --worktree	在隔离的 git worktree 中启动	claude -w
-n, --name	设置会话显示名称	claude -n "auth-refactor"
--from-pr <number>	恢复与 GitHub PR 关联的会话	claude --from-pr 42
--remote "task"	在 claude.ai 上创建 web session	claude --remote "implement API"
--remote-control, --rc	使用 Remote Control 进入交互式会话	claude --rc
--teleport	将 web session 恢复到本地	claude --teleport
--teammate-mode	agent team 显示模式	claude --teammate-mode tmux
--bare	极简模式，跳过 hooks、skills、plugins、MCP、自动记忆和 CLAUDE.md	claude --bare
--enable-auto-mode	解锁 auto permission mode	claude --enable-auto-mode
--channels	订阅 MCP channel 插件	claude --channels discord,telegram
--chrome / --no-chrome	启用 / 禁用 Chrome 浏览器集成	claude --chrome
--effort	设置推理强度	claude --effort high
--init / --init-only	运行初始化 hooks	claude --init
--maintenance	运行维护 hooks 后退出	claude --maintenance
--disable-slash-commands	禁用所有 skills 和 slash commands	claude --disable-slash-commands
--no-session-persistence	禁用会话保存（打印模式）	claude -p --no-session-persistence "query"

交互模式 vs 打印模式

graph LR
    A["claude"] -->|默认| B["交互式 REPL"]
    A -->|"-p 参数"| C["打印模式"]
    B -->|特性| D["多轮对话<br>Tab 补全<br>历史记录<br>Slash commands"]
    C -->|特性| E["单次查询<br>可脚本化<br>可管道化<br>JSON 输出"]

交互模式（默认）：

# 启动交互式会话
claude

# 带初始提示启动
claude "解释这个认证流程"

打印模式（非交互式）：

# 单次查询后退出
claude -p "这个函数做什么？"

# 处理文件内容
cat error.log | claude -p "解释这个错误"

# 与其他工具串联
claude -p "列出待办事项" | grep "URGENT"

模型与配置

参数	说明	示例
--model	设置模型（sonnet、opus、haiku，或完整模型名）	claude --model opus
--fallback-model	当前模型负载过高时自动切换的后备模型	claude -p --fallback-model sonnet "query"
--agent	为当前会话指定 agent	claude --agent my-custom-agent
--agents	通过 JSON 定义自定义 subagents	见 Agents Configuration
--effort	设置推理级别（low、medium、high、max）	claude --effort high

模型选择示例

# 复杂任务使用 Opus 4.6
claude --model opus "设计一个缓存策略"

# 快速任务使用 Haiku 4.5
claude --model haiku -p "格式化这个 JSON"

# 使用完整模型名
claude --model claude-sonnet-4-6-20250929 "审查这段代码"

# 带后备模型以提升稳定性
claude -p --model opus --fallback-model sonnet "分析架构"

# 使用 opusplan（Opus 负责规划，Sonnet 负责执行）
claude --model opusplan "设计并实现缓存层"

系统提示词自定义

参数	说明	示例
--system-prompt	替换整段默认系统提示词	claude --system-prompt "You are a Python expert"
--system-prompt-file	从文件加载提示词（仅打印模式）	claude -p --system-prompt-file ./prompt.txt "query"
--append-system-prompt	在默认提示词后追加内容	claude --append-system-prompt "Always use TypeScript"

系统提示词示例

# 完整自定义人格
claude --system-prompt "你是一名资深安全工程师，重点关注漏洞。"

# 追加特定指令
claude --append-system-prompt "始终在代码示例中包含单元测试"

# 从文件加载复杂提示词
claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py"

系统提示词参数对比

参数	行为	交互模式	打印模式
--system-prompt	替换整个默认系统提示词	✅	✅
--system-prompt-file	用文件中的提示词替换	❌	✅
--append-system-prompt	追加到默认系统提示词后	✅	✅

仅在打印模式中使用 --system-prompt-file。交互模式请使用 --system-prompt 或 --append-system-prompt。

工具与权限管理

参数	说明	示例
--tools	限制可用的内置工具	claude -p --tools "Bash,Edit,Read" "query"
--allowedTools	无需提示即可执行的工具	"Bash(git log:*)" "Read"
--disallowedTools	从上下文中移除的工具	"Bash(rm:*)" "Edit"
--dangerously-skip-permissions	跳过所有权限提示	claude --dangerously-skip-permissions
--permission-mode	以指定权限模式启动	claude --permission-mode auto
--permission-prompt-tool	用于权限处理的 MCP tool	claude -p --permission-prompt-tool mcp_auth "query"
--enable-auto-mode	解锁 auto permission mode	claude --enable-auto-mode

权限示例

# 代码审查只读模式
claude --permission-mode plan "审查这个代码库"

# 只允许安全工具
claude --tools "Read,Grep,Glob" -p "找出所有 TODO 注释"

# 允许特定 git 命令无需提示
claude --allowedTools "Bash(git status:*)" "Bash(git log:*)"

# 阻止危险操作
claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"

输出与格式

参数	说明	选项	示例
--output-format	指定输出格式（打印模式）	text、json、stream-json	claude -p --output-format json "query"
--input-format	指定输入格式（打印模式）	text、stream-json	claude -p --input-format stream-json
--verbose	启用详细日志		claude --verbose
--include-partial-messages	包含流式事件	需要 stream-json	claude -p --output-format stream-json --include-partial-messages "query"
--json-schema	获取符合 schema 的 JSON 输出		claude -p --json-schema '{"type":"object"}' "query"
--max-budget-usd	打印模式最大花费		claude -p --max-budget-usd 5.00 "query"

输出格式示例

# 纯文本（默认）
claude -p "解释这段代码"

# 供程序使用的 JSON
claude -p --output-format json "列出 main.py 中的所有函数"

# 用于实时处理的流式 JSON
claude -p --output-format stream-json "生成一份长报告"

# 使用 schema 验证的结构化输出
claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \
  "找出这段代码中的 bug，并以 JSON 返回"

工作区与目录

参数	说明	示例
--working-directory	设置工作目录	claude --working-directory /path/to/project
--add-dir	追加额外工作目录	claude --add-dir /path/to/other/project

多目录示例

# 在多个项目目录中协作
claude --working-directory ~/projects/app --add-dir ~/projects/shared

# 加载自定义设置
claude --working-directory ./backend --add-dir ./frontend

MCP 配置

参数	说明	示例
--mcp-config	从文件加载 MCP 配置	claude --mcp-config ./mcp.json
--mcp	启用 / 配置 MCP 服务	claude --mcp github
--mcp-list	列出可用 MCP 配置	claude --mcp-list

MCP 示例

# 加载 GitHub MCP server
claude --mcp-config ./configs/github-mcp.json

# 严格模式，只允许指定的 server
claude --mcp-config ./configs/strict-mcp.json --mcp github

会话管理

参数	说明	示例
--session	指定会话名称	claude --session feature-auth
--new-session	强制开启新会话	claude --new-session
--resume-last	恢复最近一次会话	claude --resume-last
--fork-session	从当前会话分叉	claude --fork-session

会话示例

# 继续上一次对话
claude --continue

# 恢复命名会话
claude --resume feature-auth

# 为实验分叉会话
claude --fork-session

# 指定会话 ID
claude --resume 123456789

会话分叉

# 分叉会话尝试不同方案
claude --fork-session "尝试另一种实现"

# 带自定义消息分叉
claude --fork-session --session "experiment-a"

高级特性

参数	说明	示例
--disable-auto-checkpoints	禁用自动 checkpoint	claude --disable-auto-checkpoints
--enable-auto-checkpoints	启用自动 checkpoint	claude --enable-auto-checkpoints
--interactive	强制交互模式	claude --interactive
--dry-run	仅模拟执行	claude --dry-run "review code"
--unsafe	允许更多自动化操作	claude --unsafe

高级示例

# 限制自主操作
claude --permission-mode plan --model opus "设计并实现认证系统"

# 调试 API 调用
claude --verbose -p "diagnose this issue"

# 启用 IDE 集成
claude --ide "review this diff"

Subagents 配置

参数	说明	示例
--agents	通过 JSON 定义自定义 subagents	claude --agents ./agents.json
--agent	指定当前会话使用的 agent	claude --agent reviewer

Subagents JSON 格式

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

必填字段：

• description - 何时使用这个 agent 的自然语言说明
• prompt - 定义 agent 角色和行为的系统提示词

可选字段：

• tools - 可用工具数组（如果省略则继承全部工具）
  • 格式：["Read", "Grep", "Glob", "Bash"]
• model - 使用的模型：sonnet、opus 或 haiku

完整 Agents 示例

{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",
    "tools": ["Read", "Edit", "Bash", "Grep"],
    "model": "opus"
  },
  "documenter": {
    "description": "Documentation specialist for generating guides.",
    "prompt": "You are a technical writer. Create clear, comprehensive documentation.",
    "tools": ["Read", "Write"],
    "model": "haiku"
  }
}

Agents 命令示例

# 直接定义自定义 agent
claude --agents '{
  "security-auditor": {
    "description": "Security specialist for vulnerability analysis",
    "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "opus"
  }
}' "audit this codebase for security issues"

# 从文件加载 agents
claude --agents ./configs/agents.json

# 与其他参数组合
claude --agents ./configs/agents.json --model opus

Subagent 优先级

当同时存在多种 agent 定义时，加载优先级如下：

1. CLI 定义（--agents 参数）- 当前会话专用
2. 用户级（~/.claude/agents/）- 所有项目可用
3. 项目级（.claude/agents/）- 当前项目可用

命令行定义的 agents 会覆盖本次会话里的用户级和项目级 agents。

高价值使用场景

1. CI/CD 集成

claude -p --output-format json "run tests and summarize failures"

2. 管道式脚本处理

# 分析错误日志
cat error.log | claude -p "解释这些错误并给出修复建议"

# 查找访问日志中的模式
cat access.log | claude -p "找出异常流量"

# 分析 git 历史
git log --oneline -20 | claude -p "总结最近的开发方向"

# 审查某个文件
claude -p "review src/app.ts and suggest improvements"

# 生成文档
claude -p "根据 README 生成 API 文档"

# 查找 TODO 并排优先级
rg -n "TODO|FIXME" . | claude -p "按优先级分类这些待办"

3. 多会话工作流

# 启动特性分支会话
claude --session feature-auth

# 之后继续该会话
claude --resume feature-auth

# 分叉尝试另一种方案
claude --fork-session

# 在不同特性会话之间切换
claude --resume feature-auth
claude --resume feature-payment

4. 自定义 agent 配置

# 将 agents 配置保存到文件
cat > agents.json <<'JSON'
{
  "agents": [
    {"name":"reviewer","description":"review code"},
    {"name":"tester","description":"write tests"}
  ]
}
JSON

# 在会话中使用这些 agent
claude --agents ./agents.json --agent reviewer

5. 批处理

# 处理多个文件
find src -name "*.ts" | xargs -I{} claude -p "review {}"

# 批量代码审查
claude -p "review all changes in this branch"

# 为所有模块生成测试
claude -p "generate tests for the modified modules"

6. 安全敏感开发

# 只读安全审计
claude --permission-mode plan -p "audit this repository"

# 阻止危险命令
claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"

# 限制自动化
claude --tools "Read,Grep,Glob" -p "inspect the codebase"

7. JSON API 集成

# 获取结构化分析结果
claude -p --output-format json "analyze this code and return findings"

# 配合 jq 处理
claude -p --output-format json "list functions" | jq '.functions[]'

# 在脚本中使用
result=$(claude -p --output-format json "summarize changes")

jq 解析示例

# 提取特定字段
claude -p --output-format json "analyze repo" | jq '.summary'

# 过滤数组元素
claude -p --output-format json "find bugs" | jq '.bugs[] | select(.severity=="high")'

# 提取多个字段
claude -p --output-format json "analyze" | jq '{summary, risk, recommendations}'

# 转成 CSV
claude -p --output-format json "list files" | jq -r '.files[] | [.name, .size] | @csv'

# 条件处理
claude -p --output-format json "check status" | jq 'if .ok then "pass" else "fail" end'

# 提取嵌套值
claude -p --output-format json "inspect" | jq '.details.metrics.coverage'

# 处理整个数组
claude -p --output-format json "find todos" | jq '.todos | length'

# 转换输出
claude -p --output-format json "review" | jq '{issues: [.issues[] | {file, line, message}]}'

模型

模型选择

# 使用短名称
claude --model sonnet
claude --model opus
claude --model haiku

# 使用 opusplan 别名（Opus 负责规划，Sonnet 负责执行）
claude --model opusplan "design and implement the caching layer"

# 会话中切换快速模式
claude --model haiku --effort low

Effort 级别（Opus 4.6）

# 通过 CLI 参数设置 effort
claude --model opus --effort high "design the architecture"

# 通过 slash command 设置 effort
/effort max

# 通过环境变量设置 effort
CLAUDE_EFFORT=medium claude --model opus

常用环境变量

环境变量	说明
ANTHROPIC_API_KEY	API key
CLAUDE_MODEL	默认模型
CLAUDE_EFFORT	默认推理强度
CLAUDE_WORKING_DIRECTORY	默认工作目录
CLAUDE_OUTPUT_FORMAT	默认输出格式
CLAUDE_MCP_CONFIG	默认 MCP 配置

快速参考

最常用命令

# 交互式会话
claude

# 快速提问
claude -p "explain this repo"

# 继续上次对话
claude -c

# 处理某个文件
claude -p "review README.md"

# 为脚本输出 JSON
claude -p --output-format json "list all classes"

参数组合

# 只读审查
claude --permission-mode plan -p "review this codebase"

# 高级模型 + JSON 输出
claude --model opus -p --output-format json "analyze architecture"

# 自定义工作目录 + MCP
claude --working-directory ./backend --mcp-config ./mcp.json

故障排查

找不到命令

• 确认 claude 已安装并在 PATH 中
• 重新打开终端
• 检查是否需要重新登录或更新版本

API Key 问题

• 检查 ANTHROPIC_API_KEY
• 确认 key 未过期
• 检查网络是否可访问 API

找不到会话

• 确认会话名称或 ID 正确
• 先运行 claude --list-sessions（如果你的版本支持）
• 检查当前账号是否一致

输出格式问题

• 使用 --output-format json 时确保输出可被解析
• 如果是流式输出，加入 --include-partial-messages

权限被拒绝

• 检查 --permission-mode
• 检查 --allowedTools 和 --disallowedTools
• 如有必要，明确允许所需工具

更多资源

• 根目录中文指南
• Slash Commands 中文参考
• MCP 文档
• Claude Code 官方 CLI 文档