cli-reference

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Reference

CLI 参考文档

Complete reference for Claude Code command-line interface.

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

When to Use

适用场景

"What CLI flags are available?"
"How do I use headless mode?"
"Claude in automation/CI/CD"
"Output format options"
"System prompt via CLI"
"How do I spawn agents properly?"

"有哪些可用的CLI参数？"
"如何使用Headless Mode？"
"Claude在自动化/CI/CD中的应用"
"输出格式选项"
"通过CLI设置系统提示词"
"如何正确生成Agent？"

Core Commands

核心命令

Command	Description	Example
`claude`	Start interactive REPL	`claude`
`claude "query"`	REPL with initial prompt	`claude "explain this project"`
`claude -p "query"`	Headless mode (SDK)	`claude -p "explain function"`
`cat file \| claude -p`	Process piped content	`cat logs.txt \| claude -p "explain"`
`claude -c`	Continue most recent	`claude -c`
`claude -c -p "query"`	Continue via SDK	`claude -c -p "check types"`
`claude -r "id" "query"`	Resume session	`claude -r "auth" "finish PR"`
`claude update`	Update version	`claude update`
`claude mcp`	Configure MCP servers	See MCP docs

命令	描述	示例
`claude`	启动交互式REPL	`claude`
`claude "query"`	带初始提示词的REPL	`claude "explain this project"`
`claude -p "query"`	Headless Mode（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文档

Session Control

会话控制

Flag	Description	Example
`--continue, -c`	Load most recent conversation	`claude --continue`
`--resume, -r`	Resume session by ID/name	`claude --resume auth-refactor`
`--session-id`	Use specific UUID	`claude --session-id "550e8400-..."`
`--fork-session`	Create new session on resume	`claude --resume abc --fork-session`

参数	描述	示例
`--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`

Headless Mode (Critical for Agents)

Headless Mode（对Agent至关重要）

Flag	Description	Example
`--print, -p`	Non-interactive, exit after	`claude -p "query"`
`--output-format`	`text` , `json` , `stream-json`	`claude -p --output-format json`
`--max-turns`	Limit agentic turns	`claude -p --max-turns 100 "query"`
`--verbose`	Full turn-by-turn output	`claude --verbose`
`--dangerously-skip-permissions`	Skip permission prompts	`claude -p --dangerously-skip-permissions`
`--include-partial-messages`	Include streaming events	`claude -p --output-format stream-json --include-partial-messages`
`--input-format`	Input format (text/stream-json)	`claude -p --input-format stream-json`

参数	描述	示例
`--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`

Tool Control

工具控制

Flag	Description	Example
`--allowedTools`	Auto-approve these tools	`"Bash(git log:*)" "Read"`
`--disallowedTools`	Block these tools	`"Bash(rm:*)" "Edit"`
`--tools`	Only allow these tools	`--tools "Bash,Edit,Read"`

参数	描述	示例
`--allowedTools`	自动批准指定工具	`"Bash(git log:*)" "Read"`
`--disallowedTools`	阻止指定工具	`"Bash(rm:*)" "Edit"`
`--tools`	仅允许使用指定工具	`--tools "Bash,Edit,Read"`

Subagent Definition (--agents flag)

子Agent定义（--agents参数）

Define custom subagents inline via JSON:

bash

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."
  }
}'

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

bash

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 Fields

Agent字段

Field	Required	Description
`description`	Yes	When to invoke this agent
`prompt`	Yes	System prompt for behavior
`tools`	No	Allowed tools (inherits all if omitted)
`model`	No	`sonnet` , `haiku` , or `claude-opus-4-5-20251101`

字段	是否必填	描述
`description`	是	何时调用该Agent的说明
`prompt`	是	定义Agent行为的系统提示词
`tools`	否	允许使用的工具（省略则继承所有工具）
`model`	否	可选值： `sonnet` 、 `haiku` 或 `claude-opus-4-5-20251101`

Key Insight

关键要点

When Lead uses Task tool, it auto-spawns from these definitions. No manual spawn needed.

当主Agent使用Task工具时，会自动从这些定义中生成子Agent，无需手动生成。

System Prompt Customization

系统提示词自定义

Flag	Behavior	Modes
`--system-prompt`	Replace entire prompt	Interactive + Print
`--system-prompt-file`	Replace from file	Print only
`--append-system-prompt`	Append to default (recommended)	Interactive + Print

Use
--append-system-prompt
for most cases - preserves Claude Code capabilities.

参数	行为	适用模式
`--system-prompt`	替换整个系统提示词	交互式+非交互式模式
`--system-prompt-file`	从文件中替换系统提示词	仅非交互式模式
`--append-system-prompt`	追加到默认提示词后（推荐使用）	交互式+非交互式模式

大多数场景推荐使用
--append-system-prompt
- 可保留Claude Code的核心功能。

Model Selection

模型选择

Flag	Description	Example
`--model`	Set model for session	`--model claude-sonnet-4-5`
`--fallback-model`	Fallback if default overloaded	`--fallback-model sonnet`

Aliases:

sonnet

opus

haiku

参数	描述	示例
`--model`	为会话设置模型	`--model claude-sonnet-4-5`
`--fallback-model`	默认模型过载时的备用模型	`--fallback-model sonnet`

别名：

sonnet

、

opus

、

haiku

MCP Configuration

MCP配置

Flag	Description	Example
`--mcp-config`	Load MCP servers from JSON	`--mcp-config ./mcp.json`
`--strict-mcp-config`	Only use these MCP servers	`--strict-mcp-config --mcp-config ./mcp.json`

参数	描述	示例
`--mcp-config`	从JSON文件加载MCP服务器配置	`--mcp-config ./mcp.json`
`--strict-mcp-config`	仅使用指定的MCP服务器	`--strict-mcp-config --mcp-config ./mcp.json`

Advanced Flags

高级参数

Flag	Description	Example
`--add-dir`	Add working directories	`--add-dir ../apps ../lib`
`--agent`	Specify agent for session	`--agent my-custom-agent`
`--permission-mode`	Start in permission mode	`--permission-mode plan`
`--permission-prompt-tool`	MCP tool for permissions	`--permission-prompt-tool mcp_auth`
`--plugin-dir`	Load plugins from directory	`--plugin-dir ./my-plugins`
`--settings`	Load settings from file/JSON	`--settings ./settings.json`
`--setting-sources`	Which settings to load	`--setting-sources user,project`
`--betas`	Beta API headers	`--betas interleaved-thinking`
`--debug`	Enable debug mode	`--debug "api,hooks"`
`--ide`	Auto-connect to IDE	`--ide`
`--chrome`	Enable Chrome integration	`--chrome`
`--no-chrome`	Disable Chrome for session	`--no-chrome`
`--enable-lsp-logging`	Verbose LSP debugging	`--enable-lsp-logging`
`--version, -v`	Output version	`claude -v`

参数	描述	示例
`--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`

Output Formats

输出格式

JSON (for parsing)

JSON（用于解析）

bash

claude -p "query" --output-format json

bash

claude -p "query" --output-format json

{"result": "...", "session_id": "...", "usage": {...}}

undefined

undefined

Streaming (for real-time monitoring)

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

bash

claude -p "query" --output-format stream-json

bash

claude -p "query" --output-format stream-json

Newline-delimited JSON events

换行分隔的JSON事件

undefined

undefined

Structured Output (schema validation)

结构化输出（Schema验证）

bash

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

bash

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

Headless Agent Pattern (CRITICAL)

Headless Agent模式（至关重要）

Proper headless agent spawn:

bash

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

Missing any of these causes hangs:

```
--session-id
```
- Track the session
```
--dangerously-skip-permissions
```
- Headless requires this
```
--max-turns
```
- Prevents infinite loops

正确的Headless Agent生成方式：

bash

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
```
- Headless模式必须设置
```
--max-turns
```
- 防止无限循环

Common Patterns

常见模式

CI/CD Automation

CI/CD自动化

bash

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

bash

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

Piped Input

管道输入

bash

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

bash

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

Multi-turn Session

多轮会话

bash

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

bash

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

Stream Monitoring

流监控

bash

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

bash

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

Keyboard Shortcuts (Interactive)

键盘快捷键（交互式模式）

Shortcut	Action
`Ctrl+C`	Cancel current
`Ctrl+D`	Exit
`Ctrl+R`	Reverse search history
`Esc Esc`	Rewind changes
`Shift+Tab`	Toggle permission mode

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

Quick Commands

快捷命令

Prefix	Action
`/`	Slash command
`!`	Bash mode
`#`	Add to memory
`@`	File mention

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