Claude Code headless mode: claude -p, --output-format json, --bare and CI flags

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.

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

Piped stdin is capped at 10MB. For bigger inputs, write the content to a file and reference the path in your prompt.

--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.

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

• text (default): plain text
• json: result, session ID and metadata, including total_cost_usd
• stream-json: newline-delimited JSON events

claude -p "Summarize this project" --output-format json | jq -r '.result'

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'

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

--allowedTools uses permission rule syntax. A trailing space and * means prefix match, so Bash(git diff *) allows any command starting with git diff.

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

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).

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

{
  "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.