Claude Code headless mode: claude -p, --output-format json, --bare and CI flags
How do I run Claude Code non-interactively with claude -p in scripts and CI?
Add -p (or --print) to any claude command to run it once without the interactive interface, for example claude -p "What does the auth module do?". Use --output-format json or stream-json for machine-readable output, --allowedTools or --permission-mode to avoid prompts, and --bare in CI so the run skips local hooks, plugins, MCP servers, auto memory and CLAUDE.md.
Compare: headless mode for scripts and CI in every AI coding agent →
Basic usage
The -p flag runs Claude Code in non-interactive mode. It reads stdin, so you can pipe data in and redirect the answer out. Claude Code exits with code 0 on success and a non-zero code when the run fails.
Ask a question
claude -p "What does the auth module do?"
Pipe a log in and write the answer to a file
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
Piped stdin is capped at 10MB. For bigger inputs, write the content to a file and reference the path in your prompt.
Start faster and reproducibly with --bare
--bare skips auto-discovery of hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory and CLAUDE.md. The docs recommend it for scripted and SDK calls and say it will become the default for -p in a future release.
Bare mode never reads OAuth credentials or the system keychain. Set ANTHROPIC_API_KEY first, or supply an apiKeyHelper in the --settings JSON.
Bare mode run
claude --bare -p "Summarize README.md" --allowedTools "Read"
- --append-system-prompt or --append-system-prompt-file: add to the system prompt
- --settings <file-or-json>: load settings
- --mcp-config <file-or-json>: load MCP servers
- --agents <file-or-json>: load custom agents
- --plugin-dir <path>: load a plugin
Get structured output
- text (default): plain text
- json: result, session ID and metadata, including total_cost_usd
- stream-json: newline-delimited JSON events
JSON output, extract the text with jq
claude -p "Summarize this project" --output-format json | jq -r '.result'
Force a JSON Schema (result lands in structured_output)
claude -p "Extract the main function names from auth.py" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
| jq '.structured_output'Stream tokens as they arrive
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
Approve tools without prompts
--allowedTools uses permission rule syntax. A trailing space and * means prefix match, so Bash(git diff *) allows any command starting with git diff.
Run tests and fix failures
claude -p "Run the test suite and fix any failures" \ --allowedTools "Bash,Read,Edit"
Commit with scoped git permissions
claude -p "Look at my staged changes and create an appropriate commit" \ --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
Or set a baseline with --permission-mode: auto (a classifier reviews most actions), dontAsk (deny anything that would prompt, good for locked-down CI) or acceptEdits (write files without prompting). Add --permission-prompts none for unattended jobs (v2.1.259 or later).
Unattended auto mode run
claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none
Continue a conversation
Continue the most recent conversation
claude -p "Review this codebase for performance issues" claude -p "Now focus on the database queries" --continue
Resume a specific session by ID
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id') claude -p "Continue that review" --resume "$session_id"
Use it in a build script
package.json typo linter
{
"scripts": {
"lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
}
}Run it with npm run lint:claude. For full programmatic control in Python or TypeScript, use the Agent SDK packages.
Sources
More Claude Code guides
- How to allow Claude Code to run all commands: permission modes, allow rules and skip permissions
- Claude Code permissions: allow, ask and deny rules, rule syntax and allowed tools
- Claude Code telemetry and data retention: what is sent and how to turn it off
- CLAUDE.md: where it goes, how it loads, and how it works with AGENTS.md
- Claude Code hooks: all events, exit codes, PreToolUse and PermissionRequest JSON, examples
- Claude Code subagents: create one, limit its tools, and call it
- Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes)
- Claude Code custom slash commands and skills (SKILL.md)
- Claude Code settings.json: file locations, precedence, and key settings
- Claude Code plugins and marketplaces: install, create, and share
- Claude Code statusline: custom status bar in settings.json with context %, cost and git branch
- Claude Code /model: switch models, aliases (opus, sonnet, haiku, opusplan), ANTHROPIC_MODEL and effort
- Claude Code /cost and /usage: check token spend, usage limits and reduce costs
- Claude Code VS Code extension: install, shortcuts, settings and /ide (works in Cursor too)
- MCP 2026-07-28 Migration Guide: Stateless Protocol, No Sessions, server/discover, MRTR, and SDK v2 Upgrade
- Subagents and Custom Agents Compared: Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub Copilot (2026)
- Allow all commands in any AI coding agent: Cursor, Claude Code, Codex, Gemini CLI, Copilot CLI and 7 more (2026)
- How to deploy a remote MCP server (Streamable HTTP): Cloudflare Workers, Vercel, Railway and more (2026)
- Claude Code sandbox: /sandbox, sandbox.enabled, allowedDomains, excludedCommands and strict mode
Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →