SpyBara
Go Premium

cli-reference.md 2026-08-03 20:02 UTC to 2026-08-04 22:59 UTC

68 added, 68 removed.

2026
Thu 6 15:02 Wed 5 22:02 Tue 4 22:59 Mon 3 20:02 Sun 2 19:00

CLI 参考

Claude Code 命令行界面的完整参考，包括命令和标志。

CLI 命令

您可以使用这些命令启动会话、管道内容、恢复对话和管理更新：

命令 描述 示例
claude 启动交互式会话 claude
claude "query" 使用初始提示启动交互式会话 claude "explain this project"
claude -p "query" 通过 SDK 查询，然后退出 claude -p "explain this function"
cat file | claude -p "query" 处理管道内容 cat logs.txt | claude -p "explain"
claude -c 在当前目录中继续最近的对话 claude -c
claude -c -p "query" 通过 SDK 继续 claude -c -p "Check for type errors"
claude -r "<session>" "query" 按 ID 或名称恢复会话 claude -r "auth-refactor" "Finish this PR"
claude update 更新到最新版本 claude update
claude gateway 启动自托管 Claude apps gateway 服务器，供在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上部署 SSO 和策略在 Claude Code 前面的管理员使用。需要 --config 指向 gateway.yaml。在 Claude Code v2.1.195 及更高版本中可用。 claude gateway --config gateway.yaml
claude install [version] 安装或重新安装本机二进制文件。接受版本号如 2.1.118、stable 或 latest。请参阅 安装特定版本 claude install stable
claude auth login 登录您的 Anthropic 账户。使用 --email 预填充您的电子邮件地址，使用 --sso 强制 SSO 身份验证，使用 --console 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 claude auth login --console
claude auth logout 从您的 Anthropic 账户登出 claude auth logout
claude auth status 以 JSON 格式显示身份验证状态。使用 --text 获取人类可读的输出。如果已登录，则以代码 0 退出，如果未登录，则以代码 1 退出 claude auth status
claude agents 打开 agent view 以监控和分派并行后台会话。使用 --cwd <path> 仅显示在该目录下启动的会话，或使用 --json 将实时会话打印为 JSON 数组以供脚本使用（--json --all 也包括已完成的后台会话）。传递 --permission-mode、--model、--effort 或 --agent 以设置 分派会话的默认值。接受 --settings、--add-dir、--plugin-dir 和 --mcp-config，如顶级 claude 命令。打开 agent view 需要交互式终端 claude agents --json
claude attach <id> 在此终端中附加到 后台会话 claude attach 7c5dcf5d
claude auto-mode defaults 以 JSON 格式打印内置 auto mode 分类器规则。使用 claude auto-mode config 查看应用了设置的有效配置。}--label <prefix> 仅打印标签以该前缀开头的规则，不区分大小写匹配。需要 Claude Code v2.1.208 或更高版本 claude auto-mode defaults --label 'Git Destructive'
claude daemon status 打印后台会话 supervisor 的状态、版本、套接字目录和工作进程数以进行诊断。如果 supervisor 未运行，则退出代码 1 claude daemon status
claude daemon stop --any 停止后台会话 supervisor 及其托管的会话。传递 --keep-workers 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。--any 确认停止按需 supervisor，这是默认值。使用此命令从 无响应的 supervisor 恢复 claude daemon stop --any --keep-workers
claude doctor 从终端打印只读安装和设置诊断，无需启动会话，包括安装健康状况、设置文件验证错误和远程控制资格。对于可以应用修复的会话内设置检查，请运行 /doctor claude doctor
claude logs <id> 从 后台会话 打印最近的输出 claude logs 7c5dcf5d
claude mcp 配置 Model Context Protocol (MCP) 服务器 请参阅 Claude Code MCP 文档。
claude mcp login <name> 运行配置的 MCP 服务器的 OAuth 流程而不打开交互式 /mcp 面板。适用于 HTTP、SSE 和 claude.ai 连接器服务器。在 SSH 上添加 --no-browser 以打印授权 URL 而不是打开浏览器，然后在提示处粘贴重定向 URL。需要 Claude Code v2.1.186 或更高版本。请参阅 从命令行进行身份验证 claude mcp login sentry
claude mcp logout <name> 清除 MCP 服务器的存储 OAuth 凭据。需要 Claude Code v2.1.186 或更高版本 claude mcp logout sentry
claude plugin 管理 Claude Code plugins。别名：claude plugins。请参阅 plugin 参考 了解子命令 claude plugin install code-review@claude-plugins-official
claude project purge [path] 删除项目的所有本地 Claude Code 状态：记录、任务列表、调试日志、文件编辑历史、提示历史行和项目在 ~/.claude.json 中的条目。省略 [path] 以从交互式列表中选择。标志：--dry-run 预览，-y/--yes 跳过确认，-i/--interactive 确认每一项，--all 用于每个项目。请参阅 清除本地数据 claude project purge ~/work/repo --dry-run
claude remote-control 启动 Remote Control 服务器以从 Claude.ai 或 Claude 应用控制 Claude Code。在服务器模式下运行（无本地交互式会话）。请参阅 服务器模式标志 claude remote-control --name "My Project"
claude respawn <id> 重启 后台会话，运行或已停止，保持其对话完整。使用 --all 重启每个运行中的会话，例如以获取更新的 Claude Code 二进制文件 claude respawn 7c5dcf5d
claude rm <id> 从列表中删除 后台会话。对话记录保留在您的本地计算机上，可通过 claude --resume 访问 claude rm 7c5dcf5d
claude setup-token 为 CI 和脚本生成长期 OAuth 令牌。将令牌打印到终端而不保存。需要 Claude 订阅。请参阅 生成长期令牌 claude setup-token
claude stop <id> 停止 后台会话。也接受 claude kill claude stop 7c5dcf5d
claude ultrareview [target] 非交互式运行 ultrareview。将发现结果打印到标准输出，成功时退出代码 0，失败时退出代码 1。使用 --json 获取原始有效负载，使用 --timeout <minutes> 覆盖 30 分钟的默认值 claude ultrareview 1234 --json

如果您输入错误的子命令，Claude Code 会建议最接近的匹配项并退出而不启动会话。例如，claude udpate 会打印 Did you mean claude update?。

从 v2.1.199 开始，claude --dangerously-skip-permissions daemon <subcommand> 运行 daemon 子命令。早期版本将 daemon <subcommand> 视为新交互式会话的提示，因此当标志在前面时子命令永远不会运行，这是 claude 别名为包含该标志时的常见设置。只有前导 --dangerously-skip-permissions 或 --allow-dangerously-skip-permissions 以这种方式路由到 daemon；任何其他前导标志仍然启动交互式会话。

CLI 标志

使用这些命令行标志自定义 Claude Code 的行为。claude --help 不会列出每个标志，因此标志在 --help 中的缺失并不意味着它不可用。

标志 描述 示例
--add-dir 为 Claude 添加额外的工作目录以读取和编辑文件。授予文件访问权限；大多数 .claude/ 配置 不会从这些目录中发现。验证每个路径是否存在为目录。要在会话间持久化这些目录，请在设置中设置 permissions.additionalDirectories claude --add-dir ../apps ../lib
--advisor <model> 为此会话启用服务器端 advisor tool，使用模型别名：opus、sonnet 或 fable（v2.1.170+），或完整模型 ID。优先于会话的 advisorModel 设置 claude --advisor opus
--agent 为当前会话指定代理（覆盖 agent 设置） claude --agent my-custom-agent
--agents 通过 JSON 动态定义自定义 subagents。使用与 subagent frontmatter 相同的字段名称，加上代理指令的 prompt 字段 claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'
--allow-dangerously-skip-permissions 将 bypassPermissions 添加到 Shift+Tab 模式循环中而不启动它。允许您以不同的模式（如 plan）开始，稍后切换到 bypassPermissions。请参阅 权限模式 claude --permission-mode plan --allow-dangerously-skip-permissions
--allowedTools, --allowed-tools 无需提示权限即可执行的工具。请参阅 权限规则语法 了解模式匹配。要限制哪些工具可用，请改用 --tools "Bash(git log *)" "Bash(git diff *)" "Read"
--append-subagent-system-prompt 将自定义文本附加到每个 subagent 的系统提示末尾，包括嵌套的 subagents。仅在非交互模式下与 -p 一起应用。需要 Claude Code v2.1.205 或更高版本 claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"
--append-system-prompt 将自定义文本附加到默认系统提示的末尾 claude --append-system-prompt "Always use TypeScript"
--append-system-prompt-file 从文件加载额外的系统提示文本并附加到默认提示 claude --append-system-prompt-file ./extra-rules.txt
--ax-screen-reader 渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。强制使用经典渲染器，因此 tui 设置在会话期间无效；附加的 后台会话 仍然全屏渲染。优先于 CLAUDE_AX_SCREEN_READER 和 axScreenReader 设置。需要 Claude Code v2.1.181 或更高版本 claude --ax-screen-reader
--bare 最小模式：跳过 hooks、skills、plugins、MCP 服务器、自动内存和 CLAUDE.md 的自动发现，以便脚本化调用启动更快。Claude 可以访问 Bash、文件读取和文件编辑工具。设置 CLAUDE_CODE_SIMPLE。请参阅 bare mode claude --bare -p "query"
--betas 要包含在 API 请求中的 Beta 标头（仅限 API 密钥用户） claude --betas interleaved-thinking
--bg, --background 启动会话作为 后台代理 并立即返回。打印会话 ID 和管理命令。与 --exec 结合以作为后台作业运行 shell 命令而不是 Claude 会话，或与 --agent 结合以运行特定的 subagent。不能与 -p/--print 结合；请参阅 错误参考 claude --bg "investigate the flaky test"
--channels （研究预览）MCP 服务器，其 channel 通知 Claude 应在此会话中侦听。以空格分隔的 plugin:<name>@<marketplace> 条目列表。需要 Claude.ai 身份验证 claude --channels plugin:my-notifier@my-marketplace
--chrome 启用 Chrome 浏览器集成 以进行网络自动化和测试 claude --chrome
--cloud 在 claude.ai 上创建新的 网络会话，提供任务描述 claude --cloud "Fix the login bug"
--continue, -c 加载当前目录中最近的对话。包括使用 /add-dir 添加此目录的会话 claude --continue
--dangerously-load-development-channels 启用不在批准的允许列表中的 channels，用于本地开发。接受 plugin:<name>@<marketplace> 和 server:<name> 条目。提示确认 claude --dangerously-load-development-channels server:webhook
--dangerously-skip-permissions 跳过权限提示。等同于 --permission-mode bypassPermissions。请参阅 权限模式 了解此操作跳过和不跳过的内容。对于使用 --bg 启动的会话，该模式 在主管重启会话时持久化 claude --dangerously-skip-permissions
--debug 启用调试模式，可选类别过滤（例如，"api,hooks" 或 "!statsig,!file"） claude --debug "api,mcp"
--debug-file <path> 将调试日志写入特定文件路径。隐式启用调试模式。优先于 CLAUDE_CODE_DEBUG_LOGS_DIR claude --debug-file /tmp/claude-debug.log
--disable-slash-commands 为此会话禁用所有 skills 和命令 claude --disable-slash-commands
--disallowedTools, --disallowed-tools 拒绝规则。裸工具名称从模型的上下文中删除匹配的工具："Edit" 删除 Edit，"*" 删除每个工具，"mcp__*" 删除每个 MCP 工具。作用域规则（如 Bash(rm *) ）使工具保持可用，仅拒绝匹配的调用 "Bash(git log *)" "Bash(git diff *)" "Edit"
--effort 为当前会话设置 工作量级别。选项：low、medium、high、xhigh、max 或 }ultracode。可用级别取决于模型。ultracode 以 xhigh 工作量启动会话，并启用 ultracode，需要 Claude Code v2.1.203 或更高版本。覆盖此会话的 effortLevel 设置，不会持久化 claude --effort high
--enable-auto-mode 在 v2.1.111 中移除。Auto mode 现在默认在 Shift+Tab 循环中；使用 --permission-mode auto 以它开始 claude --permission-mode auto
--exclude-dynamic-system-prompt-sections 将每台机器的部分从系统提示（工作目录、环境信息、内存路径、git 状态）移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示缓存重用。仅适用于默认系统提示；当设置 --system-prompt 或 --system-prompt-file 时忽略。与 -p 一起用于脚本化的多用户工作负载 claude -p --exclude-dynamic-system-prompt-sections "query"
--exec 运行 shell 命令作为 PTY 支持的后台作业而不是启动 Claude 会话。与 --bg 一起使用以从 shell 启动 claude --bg --exec 'pytest -x'
--fallback-model 当主模型过载或不可用时启用自动回退到指定的模型，例如已停用的模型。接受逗号分隔的列表，按顺序尝试。请参阅 Fallback model chains。要在会话间持久化链，请使用 fallbackModel 设置，此标志会覆盖它 claude --fallback-model sonnet,haiku
--fork-session 恢复时，创建新的会话 ID 而不是重用原始 ID（与 --resume 或 --continue 一起使用） claude --resume abc123 --fork-session
--from-pr 恢复链接到特定拉取请求的会话。接受 PR 号、GitHub 或 GitHub Enterprise PR URL、GitLab 合并请求 URL 或 Bitbucket 拉取请求 URL。当 Claude 创建拉取请求时会自动链接会话 claude --from-pr 123
--ide 如果恰好有一个有效的 IDE 可用，则在启动时自动连接到 IDE claude --ide
--init 在会话前运行带有 init 匹配器的 Setup hooks（仅打印模式） claude -p --init "query"
--init-only 运行 Setup 和 SessionStart hooks，然后退出而不启动对话 claude --init-only
--include-hook-events 在输出流中包含所有 hook 生命周期事件。SessionStart 和 Setup hook 事件始终包含，不需要此标志。需要 --output-format stream-json claude -p --output-format stream-json --verbose --include-hook-events "query"
--include-partial-messages 在输出中包含部分流事件。需要 --print 和 --output-format stream-json claude -p --output-format stream-json --verbose --include-partial-messages "query"
--input-format 为打印模式指定输入格式（选项：text、stream-json） claude -p --output-format json --input-format stream-json
--json-schema 在代理完成其工作流后获得与 JSON Schema 匹配的验证 JSON 输出（仅打印模式）。请参阅 结构化输出。Claude Code 在无效的 schema 上以错误退出，并接受 format 关键字作为注释而无需客户端验证。在 v2.1.205 之前，无效的 schema 产生无结构的输出且没有错误，使用 format 的 schemas 被视为无效 claude -p --json-schema '{"type":"object","properties":{...}}' "query"
--maintenance 在会话前运行带有 maintenance 匹配器的 Setup hooks（仅打印模式） claude -p --maintenance "query"
--max-budget-usd API 调用前停止的最大美元金额（仅打印模式） claude -p --max-budget-usd 5.00 "query"
--max-turns 限制代理转数（仅打印模式）。达到限制时以错误退出。默认无限制。使用 --input-format stream-json 时，在 Claude 工作时发送的消息保持排队，并在限制结束当前转时作为其自己的转运行，具有其自己的限制。在 v2.1.205 之前，Claude Code 丢弃该消息 claude -p --max-turns 3 "query"
--mcp-config 从 JSON 文件或字符串加载 MCP 服务器（以空格分隔） claude --mcp-config ./mcp.json
--model 为当前会话设置模型，使用最新模型的别名（sonnet、opus、haiku 或 fable）或模型的完整名称。覆盖 model 设置和 ANTHROPIC_MODEL claude --model claude-sonnet-5
--name, -n 为会话设置显示名称，显示在 /resume 和终端标题中。您可以使用 claude --resume <name> 恢复命名会话。

/rename 在会话中更改名称，也会在提示栏中显示		 claude -n "my-feature-work"
--no-chrome 为此会话禁用 Chrome 浏览器集成 claude --no-chrome
--no-session-persistence 禁用会话持久化，以便会话不会保存到磁盘且无法恢复。仅打印模式。CLAUDE_CODE_SKIP_PROMPT_HISTORY 环境变量在任何模式下都做同样的事情 claude -p --no-session-persistence "query"
--output-format 为打印模式指定输出格式（选项：text、json、stream-json） claude -p "query" --output-format json
--permission-mode 以指定的 权限模式 开始。接受 default、acceptEdits、plan、auto、dontAsk、bypassPermissions 或 }manual 作为 default 的别名。manual 别名选择 UI 标记为"手动"的模式，需要 Claude Code v2.1.200 或更高版本；claude --help 用它代替 default 列出它，两个值都有效。覆盖设置文件中的 defaultMode claude --permission-mode plan
--permission-prompt-tool 指定 MCP 工具以在非交互模式下处理权限提示。Claude Code 等待该工具的 MCP 服务器连接后再运行第一轮，最多等待 MCP_TIMEOUT 启动超时 30 秒。在 v2.1.206 之前，启动缓慢的服务器可能会导致运行 以错误退出，表示未找到 MCP 工具。

提示工具无法批准标记为 需要用户交互 的 MCP 工具：Claude Code 将其中一个的 allow 结果转换为拒绝。此限制需要 Claude Code v2.1.199 或更高版本		 claude -p --permission-prompt-tool mcp_auth_tool "query"
--plugin-dir 仅为此会话从目录或 .zip 存档加载插件。每个标志采用一个路径。重复该标志以获取多个插件：--plugin-dir A --plugin-dir B.zip claude --plugin-dir ./my-plugin
--plugin-url 仅为此会话从 URL 获取插件 .zip 存档。重复该标志以获取多个插件，或在单个引用值中传递以空格分隔的 URL claude --plugin-url https://example.com/plugin.zip
--print, -p 打印响应而不进入交互模式（请参阅 Agent SDK 文档 了解编程使用详情） claude -p "query"
--prompt-suggestions 在每轮后发出 prompt_suggestion 消息，带有预测的下一个用户提示。需要 --print、--output-format stream-json 和 --verbose。请参阅 提示建议 claude -p --prompt-suggestions --output-format stream-json --verbose "query"
--remote 已弃用的 --cloud 别名 claude --remote "Fix the login bug"
--remote-control, --rc 启动启用了 Remote Control 的交互式会话，以便您也可以从 claude.ai 或 Claude 应用控制它。可选地为会话传递名称 claude --remote-control "My Project"
--remote-control-session-name-prefix <prefix> 当未设置显式名称时，Remote Control 自动生成会话名称的前缀。默认为您的机器的主机名，生成名称如 myhost-graceful-unicorn。设置 CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX 以获得相同效果 claude remote-control --remote-control-session-name-prefix dev-box
--replay-user-messages 从 stdin 重新发出用户消息到 stdout 以进行确认。需要 --input-format stream-json 和 --output-format stream-json claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages
--resume, -r 按 ID 或名称恢复特定会话，或显示交互式选择器以选择会话。选择器和名称搜索包括使用 /add-dir 添加此目录的会话；传递会话 ID 仅搜索当前项目目录及其 git worktrees。截至 v2.1.144，后台会话 在选择器中显示，标记为 bg claude --resume auth-refactor
--safe-mode 以所有自定义禁用的状态启动以排查损坏的配置：CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令和代理、输出样式、工作流、自定义主题、自定义快捷键、状态行和文件建议命令、LSP 服务器和自动内存不加载。身份验证、模型选择、内置工具和权限正常工作，这与 --bare 不同。托管设置策略仍然适用，包括策略配置的 hooks、状态行和文件建议命令；托管插件、托管 skills、托管 CLAUDE.md 和策略配置的 MCP 服务器不适用。用于检查自定义是否触发 从 Fable 5 自动回退。设置 CLAUDE_CODE_SAFE_MODE claude --safe-mode
--session-id 为对话使用特定的会话 ID（必须是有效的 UUID） claude --session-id "550e8400-e29b-41d4-a716-446655440000"
--setting-sources 逗号分隔的设置源列表以加载（user、project、local） claude --setting-sources user,project
--settings 设置 JSON 文件的路径或内联 JSON 字符串。您在此处设置的值会覆盖此会话的 settings.json 文件中的相同键。您省略的键保留其基于文件的值。请参阅 设置优先级 claude --settings ./settings.json
--strict-mcp-config 仅使用来自 --mcp-config 的 MCP 服务器，忽略所有其他 MCP 配置 claude --strict-mcp-config --mcp-config ./mcp.json
--system-prompt 用自定义文本替换整个系统提示 claude --system-prompt "You are a Python expert"
--system-prompt-file 从文件加载系统提示，替换默认提示 claude --system-prompt-file ./custom-prompt.txt
--teleport 在本地终端中恢复 网络会话 claude --teleport
--teammate-mode 设置 agent team 队友的显示方式：in-process（默认）、auto、tmux 或 }iterm2（在 v2.1.186 中添加）。默认值在 v2.1.179 中从 auto 更改。覆盖此会话的 teammateMode 设置。请参阅 选择显示模式 claude --teammate-mode auto
--tmux 为 worktree 创建 tmux 会话。需要 --worktree。在可用时使用 iTerm2 原生窗格；传递 --tmux=classic 以使用传统 tmux claude -w feature-auth --tmux
--tools 限制 Claude 可以使用的内置工具。使用 "" 禁用所有，"default" 表示全部，或工具名称如 "Bash,Edit,Read"。MCP 工具不受影响；要拒绝这些工具，请改用 --disallowedTools "mcp__*"，或传递 --strict-mcp-config 而不带 --mcp-config 以便不加载 MCP 服务器 claude --tools "Bash,Edit,Read"
--verbose 启用详细日志记录，显示完整的逐轮输出。覆盖此会话的 viewMode 设置 claude --verbose
--version, -v 输出版本号 claude -v
--worktree, -w 在隔离的 git worktree 中启动 Claude，位于 <repo>/.claude/worktrees/<name>。如果未给出名称，则自动生成一个。传递 #<number> 或 GitHub 拉取请求 URL 以从 origin 获取该 PR 并从其分支 worktree claude -w feature-auth

系统提示标志

Claude Code 提供四个标志用于自定义系统提示。所有四个都在交互和非交互模式下工作。

标志 行为 示例
--system-prompt 替换整个默认提示 claude --system-prompt "You are a Python expert"
--system-prompt-file 用文件内容替换 claude --system-prompt-file ./prompts/review.txt
--append-system-prompt 附加到默认提示 claude --append-system-prompt "Always use TypeScript"
--append-system-prompt-file 将文件内容附加到默认提示 claude --append-system-prompt-file ./style-rules.txt

--system-prompt 和 --system-prompt-file 互斥。附加标志可以与任一替换标志组合。

根据 Claude Code 的默认身份是否仍然适合您的任务来选择。当 Claude 应该保持编码助手身份同时遵循您的额外规则时，使用附加标志：每次调用的指令、输出格式或 -p 脚本的域上下文。附加保留默认工具指导、安全指令和编码约定，因此您只需提供不同的部分。当表面、身份或权限模型与 Claude Code 的不同时，使用替换标志，例如管道中没有人监视的非编码代理。替换会删除整个默认提示，包括工具指导和安全指令，因此您需要对任务仍然需要的任何内容负责。

这些标志仅适用于当前调用。对于可以在项目中切换和共享的持久化角色，请使用 输出样式。对于 Claude 应该始终遵循的项目约定，请使用 CLAUDE.md。Agent SDK 系统提示指南 更深入地涵盖了相同的决策。

另请参阅