它到底是什么

-p（完整写法 --print）让 claude 不进入交互式界面，而是以非交互模式运行：接收一条 prompt，跑完 agent loop，把结果打印到 stdout 后退出。官方 CLI 参考对它的定义是"Print response without interactive mode"，并指向 Agent SDK 文档了解编程用法。官方 headless 文档把这种用法称为通过 CLI 使用 Agent SDK（claude -p），拿到的是和 Claude Code 相同的 Tool、agent loop 和上下文管理。

• 取值：-p 用来开启非交互模式，prompt 直接写在命令行里（claude -p "query"）。也可以省略位置参数，从 stdin 读入（官方示例 gh pr diff "$1" | claude -p --append-system-prompt "..."）。
• 默认输出格式：--output-format 默认 text，可选 json、stream-json。
• 退出码：成功为 0，运行失败为非 0。无效 flag 会在运行前向 stderr 报错。运行中的失败（如缺少认证）会作为 result 打印到 stdout。

用法

# 最基本用法
claude -p "What does the auth module do?"

# 管道输入,结果重定向到文件
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

# 预授权 Tool,免去权限弹窗
claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"

# 结构化输出,用 jq 取字段
claude -p "Summarize this project" --output-format json | jq -r '.result'

# 续接对话
claude -p "Review this codebase for performance issues"
claude -p "Now focus on the database queries" --continue

--output-format json 的返回包含 result、session ID 和 metadata，还包含 total_cost_usd 以及分模型的成本明细。官方注明这些数字是客户端估算，可能与实际账单不同。

与其他 flag 的组合 / 互斥

仅用于 print 模式的 flag（官方 CLI 参考中，--json-schema、--max-turns、--max-budget-usd、--no-session-persistence 标注为 print mode only，其余写作 for print mode、in print mode 或 Requires --print），摘录常用项：

依赖关系：

• --include-partial-messages 需要 --print + --output-format stream-json
• --prompt-suggestions 需要 --print + --output-format stream-json + --verbose
• --replay-user-messages 需要 --input-format stream-json + --output-format stream-json
• --json-schema 的官方示例与 --output-format json 搭配使用，结构化结果出现在 structured_output 字段

明确不兼容：官方 headless 文档写明"Not every CLI option combines with -p":--bg 会被拒绝；--cloud 带任务描述时也会被拒绝，并给出指明冲突的错误。

常用搭配：--continue / --resume、--allowedTools、--permission-mode、--append-system-prompt、--bare。

运行约束 / 限制

-p 下的权限起始模式：官方文档写明 -p 的内置起始权限模式是 Manual，需要其他行为时自行传 --permission-mode（auto、dontAsk、acceptEdits）。

经典使用场景

以下均来自官方 headless 文档的示例：

• CI / 脚本：claude --bare -p "Summarize README.md" --allowedTools "Read"。--bare 跳过 Hook、Skill、plugin、MCP server、auto memory 和 CLAUDE.md 的自动发现，让每台机器上结果一致；官方称其是脚本和 SDK 调用的推荐模式，并将在未来版本成为 -p 的默认。bare 模式不读取 OAuth 凭据或系统 keychain，需要设置 ANTHROPIC_API_KEY。
• 构建脚本里的 linter：git diff main | claude -p "you are a typo linter. ..."。
• PR 安全审查：gh pr diff "$1" | claude -p --append-system-prompt "You are a security engineer. Review for vulnerabilities." --output-format json。
• 自动提交：用 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)" 只放行指定的 git 子命令。
• 实时流式：--output-format stream-json --verbose --include-partial-messages，最后一行是含最终文本、成本和会话 metadata 的 result 消息。
• 无人值守：--permission-mode auto --permission-prompts none，任何会弹提示的请求被拒绝，且告知 Claude 不要重试。
• 多步会话：用 --output-format json | jq -r '.session_id' 取 session ID，再 --resume "$session_id" 续接。

常见坑

• --allowedTools 的空格：官方明确说明 Bash(git diff *) 里 * 前的空格很重要，写成 Bash(git diff*) 会同时匹配 git diff-index。
• --continue 与 -p 会话：官方 CLI 参考说明，不带 -p 的 --continue 会跳过由 claude -p 或 Agent SDK 创建的会话；claude -p --continue 才包含它们。
• --json-schema 无效时：会报 Error: --json-schema is not a valid JSON Schema。官方说明 v2.1.205 之前会静默忽略无效 schema 并返回非结构化文本。
• 成本数字是估算：total_cost_usd 是客户端估算，不能当作账单依据。
• --max-turns 触顶是报错退出（官方 CLI 参考：Exits with an error when the limit is reached），脚本需要处理这种情况。

来源

• Run Claude Code programmatically(headless)
• CLI reference（原始起点 docs.claude.com/en/docs/claude-code/cli-reference 会 301 跳转到此地址）