Claude Code Headless Mode
How to use Claude Code headless or non-interactively with -p, JSON output, permissions, credentials, CI workflows, and safety checks.
Headless mode means running Claude Code without a normal interactive chat loop. The most common form is print mode:
claude -p "summarize the current diff"Use it for scripts, CI checks, structured output, and repeatable automation. Do not use it as an uncontrolled agent loop.
Last checked on May 24, 2026. Claude Code CLI flags and automation behavior change. Verify the current CLI reference before depending on a CI workflow.
Short Answer
Use claude -p for one-shot automation. Add explicit output format, permissions, credentials, and failure handling before putting it in CI.
Useful Flags
| Flag | Use |
|---|---|
-p, --print | Run a prompt and print the result without interactive mode. |
--output-format text | Human-readable output. |
--output-format json | Machine-readable single response. |
--output-format stream-json | Streaming machine-readable events. |
--permission-mode plan | Analyze without editing source. |
--allowedTools | Pre-approve specific tools for non-interactive runs. |
--disallowedTools | Deny tools or risky tool patterns. |
--bare | Skip auto-discovery such as hooks, skills, plugins, MCP, auto memory, and CLAUDE.md. |
--fallback-model | Use a fallback model for print or background runs when the default is overloaded. |
Good Headless Use Cases
- Summarize a diff for a pull request.
- Generate release notes from commits.
- Check whether a migration plan touches forbidden directories.
- Produce JSON for an internal review pipeline.
- Run a read-only repository audit.
Risky Use Cases
- Giving write tools to a CI job without review.
- Running with broad MCP servers and production credentials.
- Letting a loop retry indefinitely after failures.
- Assuming subscription OAuth and API key billing behave the same way.
- Running on untrusted pull requests with powerful tools.
Safer CI Pattern
claude -p "Review this diff for risky changes. Do not edit files." \
--permission-mode plan \
--output-format json \
--allowedTools "Read" "Grep" "Glob"For scripts, confirm credentials deliberately. ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, cloud-provider variables, and OAuth tokens can change how the run is billed and authorized.
When to Use the Agent SDK Instead
Use the Agent SDK when you need a long-running process, structured sessions, custom tool orchestration, embedded approvals, or production service boundaries. Use claude -p when a shell command is enough.