命令字典
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
打印响应而不使用交互模式
--printclaude -p "query"--print（别名 -p）让 claude 命令跳过交互式 REPL，以非交互（headless）模式运行：接收一次 prompt，让 Claude Code 跑完整的 agent loop，把结果打印到 stdout 后退出。官方文档称其为 Agent SDK 的 CLI 形态——"available as a CLI for scripts and CI/CD"。
该 flag 不接受值，只是一个开关；默认（不加时）是交互模式。加上 -p 后，默认输出格式是纯文本（text）。
claude -p "query"
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
也可以通过 stdin 管道输入：
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
官方文档未提到 -p 本身有等价的环境变量或 settings.json 字段——它是纯 CLI 启动行为开关。
互斥 / 会被拒绝的组合：
| 组合 | 结果 |
|---|---|
-p + --bg | Claude Code 拒绝，报错说明冲突 |
-p + --cloud <task description> | 拒绝，报错说明冲突 |
-p + --cloud <session ID> | 不拒绝，但语义变了：把消息作为 follow-up 排队进那个已存在的 cloud session，然后退出 |
常搭配使用的 flag:
--continue / --resume：延续之前的对话--allowedTools：预先授权工具，避免在无人值守时卡在权限确认上--permission-mode：设置整个 session 的权限基线（auto / dontAsk / acceptEdits），因为 -p 模式下 starting permission mode 固定是 Manual，不显式设置时，一旦触发需要确认的动作就会被拒绝或卡住（工作目录内的文件读取、只读命令集等无需审批的操作仍会正常执行）--permission-prompts none：在没有人能应答权限提示的场景（如定时任务）下，让所有本该弹出提示的动作直接被拒绝，而不是等待--output-format text|json|stream-json：控制输出结构--input-format stream-json：配合 --output-format json 从 stdin 读结构化输入--verbose + --include-partial-messages：配合 --output-format stream-json 实现逐 token 流式输出--json-schema：配合 --output-format json，让输出中额外带一个符合指定 JSON Schema 的 structured_output 字段--bare：跳过 hooks、skills、自定义命令、插件、MCP server、auto memory、CLAUDE.md 的自动发现，官方标注为"-p 的推荐模式，未来会成为 -p 的默认值"| 约束 | 原因 / 来源 |
|---|---|
默认无 --bare 时，-p 会加载与交互式会话相同的 context，包括当前目录下 .claude/settings.json 里的 hooks 和 .mcp.json 里的 MCP server，即便是从未信任过的目录，也不会弹出工作区信任对话框或逐 server 审批提示 | 官方 headless 文档明确警告这一点，建议用 --bare 规避 |
| 管道输入（stdin）上限 10MB，超过会以非零状态码报错退出 | 官方文档明确说明，建议改用文件路径 |
Claude Code 在 -p 运行中启动的后台 Bash 任务（如 dev server），会在最终结果返回、stdin 关闭约 5 秒后被终止 | 官方文档，给一个宽限期让"刚好在结果之后完成"的任务仍能交付输出 |
若 -p 运行中启动了后台 subagent 或 workflow，进程会一直等到该工作完成才退出；默认持续空闲等待 10 分钟后强制结束并丢弃部分结果，可用 CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS 调整或设为 0 取消上限 | 官方文档 |
用 SIGTERM 终止 -p 进程会导致退出码 143，当前 turn 不完整、无结果记录；要"体面结束"当前 turn 应发 SIGINT 或调用 Agent SDK 的 interrupt() | 官方文档 |
| 退出码约定：成功为 0，失败为非零，方便脚本判断分支；无效 flag 会在运行开始前把错误打到 stderr；运行中途失败（如缺少认证）则把失败信息作为 result 打印到 stdout | 官方文档 |
package.json 里把 git diff 管道给 claude -p 做 typo lint，或跑测试套件并自动修复失败用例--output-format json 拿到 result、session_id、total_cost_usd 等字段，再用 jq 提取--output-format stream-json --verbose --include-partial-messages，逐 token 展示生成过程，或跟踪 subagent 的执行消息--continue/--resume 串联多次 -p 调用，实现分步骤的自动化审查流程gh pr diff "$1" | claude -p --append-system-prompt "You are a security engineer..." --output-format json-p 就等于全自动，实际上不显式传 --permission-mode 或 --allowedTools，一旦触发需要确认的动作，-p 模式下没有人可以应答，运行会被拒绝或卡住。--bare 时会静默加载不受信任目录的 hooks 和 MCP server：因为 -p 模式不会弹出工作区信任对话框，官方文档专门提示这是需要注意的行为差异，CI/脚本场景建议始终加 --bare。--json-schema 校验行为在版本间发生过变化：官方文档提到，在 v2.1.205 之前，无效 schema 会被静默忽略并退化为非结构化文本，且任何包含 format 关键字的 schema 都会被误判为无效；之后的版本会直接报错 Error: --json-schema is not a valid JSON Schema。--permission-prompts 需要较新版本：该 flag 要求 Claude Code v2.1.259 或更高版本，更早版本会把它当作未知选项直接报错。stream-json 消费过慢可能丢内容：官方文档提到，v2.1.214 之前退出等待上限约 2 秒，消费慢的下游可能读不到完整的流式响应；之后版本改为按队列积压量动态等待，最多 30 秒。