Claude Headless
Programmatic usage of Claude Code CLI. Three modes available:
Quick Start
One-shot — single prompt, get result, exit:
claude -p "Explain this error" --output-format json
Stream JSON — bidirectional real-time NDJSON over stdin/stdout:
claude -p --output-format stream-json --input-format stream-json --verbose
# Send: {"type":"user","message":{"role":"user","content":"hello"}}
# Recv: {"type":"assistant","message":{...}}
# Recv: {"type":"result","subtype":"success",...}
Resume — continue a previous session:
claude -p "continue the review" --resume <session-id> --output-format json
Key Flags
| Flag |
Purpose |
-p / --print |
Non-interactive mode |
--output-format stream-json |
NDJSON event stream on stdout |
--input-format stream-json |
NDJSON messages on stdin (multi-turn) |
--bare |
Skip CLAUDE.md, hooks, skills, plugins, MCP, auto-memory, OAuth/keychain (fast CI; see auth.md) |
--allowedTools "Bash,Read" |
Pre-approve specific tools |
--max-budget-usd N |
Cost cap |
--json-schema '{...}' |
Structured output extraction |
For complete flag reference, read references/cli-flags.md.
Deep References
Load these on demand based on what the user needs:
references/cli-flags.md — Complete CLI flags: headless, permissions, budget, session, system prompt, subcommandsreferences/auth.md — Authentication: subscription OAuth, API key, apiKeyHelper, --bare caveat, token storagereferences/env-vars.md — Complete environment variables: auth, models, thinking, bash/network timeouts, telemetry, TLS, session, plugins, MCP, detectionreferences/stream-json.md — Stream JSON protocol: stdout events, stdin messages, pipe-chainingreferences/agent-view.md — Background sessions & claude agents: --bg, supervisor, shell management commands, peek/attach, worktree isolation, vs claude-dmreferences/permissions.md — Headless permission modes, --allowedTools, --permission-prompt-tool MCPreferences/sdks.md — TypeScript and Python Agent SDKs: API, options, streaming, multi-turnreferences/patterns.md — Real-world patterns: CI/CD, bot bridges, structured extraction, Agent Teams headless
1---2name: claude-headless-23description: Programmatic/headless Claude Code usage — CLI flags, stream-json protocol, Agent SDKs, session management. Use before spawning Claude as a subprocess, testing skill or agent behavior, running "claude -p", or building with the Agent SDK.4---56# Claude Headless78Programmatic usage of Claude Code CLI. Three modes available:910## Quick Start1112**One-shot** — single prompt, get result, exit:13```bash14claude -p "Explain this error" --output-format json15```1617**Stream JSON** — bidirectional real-time NDJSON over stdin/stdout:18```bash19claude -p --output-format stream-json --input-format stream-json --verbose20# Send: {"type":"user","message":{"role":"user","content":"hello"}}21# Recv: {"type":"assistant","message":{...}}22# Recv: {"type":"result","subtype":"success",...}23```2425**Resume** — continue a previous session:26```bash27claude -p "continue the review" --resume <session-id> --output-format json28```2930## Key Flags3132| Flag | Purpose |33|---|---|34| `-p` / `--print` | Non-interactive mode |35| `--output-format stream-json` | NDJSON event stream on stdout |36| `--input-format stream-json` | NDJSON messages on stdin (multi-turn) |37| `--bare` | Skip CLAUDE.md, hooks, skills, plugins, MCP, auto-memory, OAuth/keychain (fast CI; see `auth.md`) |38| `--allowedTools "Bash,Read"` | Pre-approve specific tools |39| `--max-budget-usd N` | Cost cap |40| `--json-schema '{...}'` | Structured output extraction |4142For complete flag reference, read `references/cli-flags.md`.4344## Deep References4546Load these on demand based on what the user needs:4748- **`references/cli-flags.md`** — Complete CLI flags: headless, permissions, budget, session, system prompt, subcommands49- **`references/auth.md`** — Authentication: subscription OAuth, API key, apiKeyHelper, `--bare` caveat, token storage50- **`references/env-vars.md`** — Complete environment variables: auth, models, thinking, bash/network timeouts, telemetry, TLS, session, plugins, MCP, detection51- **`references/stream-json.md`** — Stream JSON protocol: stdout events, stdin messages, pipe-chaining52- **`references/agent-view.md`** — Background sessions & `claude agents`: `--bg`, supervisor, shell management commands, peek/attach, worktree isolation, vs claude-dm53- **`references/permissions.md`** — Headless permission modes, --allowedTools, --permission-prompt-tool MCP54- **`references/sdks.md`** — TypeScript and Python Agent SDKs: API, options, streaming, multi-turn55- **`references/patterns.md`** — Real-world patterns: CI/CD, bot bridges, structured extraction, Agent Teams headless
archibate