Claude Code headless mode: claude -p, flags, and CI

One prompt, then the process exits. Flags from Claude Code 2.1.316, JSON you can parse, and a workflow that was checked and not run.

By David · Published November 1, 2026 · 12 min read

What Claude Code headless mode is

Claude Code non-interactive mode is the phrase the CLI uses. On November 1, 2026, claude --help for version 2.1.316 opened with this: the program starts an interactive session by default, and -p / --print is for non-interactive output. The docs page is Run Claude Code programmatically. Its URL path is /headless. The help text does not contain the word headless. The flag is the same thing.

claude -p "What does the auth module do?"

That line is the docs’ example. I did not run it. No API key was set on this machine, so there is no model answer, no timing, and no cost in this post.

The help text for --print says the workspace trust dialog is skipped, and that you should only use the flag in directories you trust. Settings files that fail validation are ignored, with no error dialog. Piped stdin works. The same docs page says the pipe is capped at 10MB, and that a success exits 0. I did not fill the pipe, and I did not see a success exit from the model.

Two commands that fail before a prompt did run. claude -p --not-a-real-flag exited 1 and printed error: unknown option '--not-a-real-flag'. claude -p --bg "hello" also exited 1. The first sentence of that error says --bg and --print conflict, because --print never starts the session that claude agents would attach to. The CLI reference says the same conflict. Stdout was empty both times.

A slash command you type at the start of a chat is a different interface. The headless page says a skill name inside the prompt string still expands, and that built-ins which only exist in the terminal, such as /login, do not. Claude Code slash commands is the file that creates /name, and the validator run on three starter files.

The flags that matter

claude --help on 2.1.316 printed 313 lines and 66 options. The table is 24 of those 66. Each row is a flag the help text actually prints. The other 42 are interactive, desktop, cloud, debug, and the rest. Descriptions are shortened from that help text. The date is November 1, 2026.

The headless page describes --bare more broadly than that help line. It says bare mode skips auto-discovery of hooks, skills, custom commands, subagents, plugins, MCP servers, auto memory, and CLAUDE.md. The 2.1.316 help line lists hooks from settings and plugins, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. It also says skills still resolve when you type /skill-name, and that you pass context yourself with --agents, --mcp-config, --settings, and --plugin-dir. I did not run --bare, so this is the text, not a directory listing I watched.

How to write a Claude MD file is the file --bare skips. Claude Code subagents is the worker you would otherwise put in .claude/agents/. The --agents flag is the help text’s way to pass one on the command line.

Claude Code output format JSON

The help choices are text, json, and stream-json. text is the default. json is one object. stream-json is one JSON object per line while the run is going.

The headless page says the text sits in result, and that the object also carries total_cost_usd plus a per-model breakdown. Their read is:

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

A second example on that page stores session_id with jq -r '.session_id', then passes it to --resume. I did not run either command.

The per-model object is named on the cost-tracking page that the headless page links for this. The result message has type result, total_cost_usd, usage, and modelUsage. usage counts tokens as input_tokens and output_tokens. modelUsage maps a model name to costUSD, inputTokens, and outputTokens. The page says total_cost_usd is a client-side estimate, not the bill. How to check Claude Code usage is the separate walkthrough for the subscription meter a headless run draws on when you authenticate with the OAuth token.

The bar under an interactive prompt reads a different object. A statusline script for session cost uses cost.total_cost_usd from the JSON Claude Code pipes to the status line command.

--json-schema puts structured output in structured_output. The headless page says a run can finish with that field missing, so check before you read it. --output-format stream-json needs --verbose on the docs’ streaming example, and --include-partial-messages if you want the token chunks. The last line of that stream is a result message.

The file documented-result.json is those field names and nothing else. Every number is 0. The result string says it is a placeholder. It is not a model answer. The script reads it with the same jq the docs use:

jq -e 'has("result") and (.result | type == "string")' documented-result.json
jq -r '.result' documented-result.json

jq 1.7 printed the placeholder sentence and exited 0. A copy with no result field exited 1. That test is in What we tested.

Permissions without a confirmation prompt

Running Claude Code without confirmation is a permission mode, not a second product. The Claude Code don’t ask mode is --permission-mode dontAsk.

The permission modes page says dontAsk denies every call that would have prompted. Reads in the working directory, and tools you already allowed, still run. --allowedTools "Read" is the narrow allow. The help example of a wider one is Bash(git *). The space before * matters on the headless page: Bash(git diff *) matches git diff, and Bash(git diff*) also matches git diff-index.

--permission-prompts none is the other switch in the help text. The choice none denies anything that would prompt. The headless page says the flag needs Claude Code v2.1.259 or later. 2.1.316 prints it. I did not pass it to a live run.

--dangerously-skip-permissions is the one to refuse by default. The help line says it bypasses all permission checks, and recommends it only for sandboxes with no internet access. The permission-mode page says the same flag is --permission-mode bypassPermissions, that tool calls then run immediately, including writes to paths the other modes protect, and that the mode offers no protection against prompt injection. A sentence in a file you cloned can ask for a shell command. This mode does not stop to ask you. On Linux and macOS the CLI refuses the mode when you are root. The template does not pass the flag. A GitHub Actions runner that holds your repo and a token is not a sandbox with the network off.

The headless page also says a -p run shows no workspace trust dialog and no per-server approval prompt. Without --bare, it connects the MCP servers in .mcp.json even in a folder you have not trusted. Add an MCP server to Claude Code is the command that writes that file, and the approval an interactive session still asks for.

Auth for a headless run

Two environment variables, from the authentication docs. Checked the same day.

• ANTHROPIC_API_KEY is a key from the Claude Console. In -p mode the docs say the key is used when it is present. You do not get the interactive approve-this-key prompt.
• CLAUDE_CODE_OAUTH_TOKEN is a long-lived token from claude setup-token. The command needs a Claude subscription: Pro, Max, Ultra, Team, or Enterprise. The token prints once. The docs say to put it in the environment. It is not saved for you.

--bare changes the second one. The help text says Anthropic auth is then strictly ANTHROPIC_API_KEY or apiKeyHelper via --settings, and that OAuth and the keychain are never read. The authentication page says the same thing in one sentence: bare mode does not read CLAUDE_CODE_OAUTH_TOKEN. If the script passes --bare, use the API key. If you only have the subscription token, do not pass --bare. The script in the template follows that split. If both variables are set, it takes the API key path, which matches the precedence on that page.

I did not run claude setup-token. I did not set either variable. A prompt was not sent.

Claude Code GitHub Actions

The GitHub Actions page shows anthropics/claude-code-action@v1. You pass anthropic_api_key or claude_code_oauth_token. The examples there use actions/checkout@v6. Quick setup stores the API key as ANTHROPIC_API_KEY and the subscription token as CLAUDE_CODE_OAUTH_TOKEN. I did not install the GitHub App, and I did not run that action.

The template here is the CLI form of the same job, because the command on the headless page is claude -p. Copy claude-headless.yml to .github/workflows/claude-headless.yml in a repository of your own, and claude-headless.sh to scripts/claude-headless.sh. The same files are listed on Templates. Do not commit a key.

name: Claude Code headless

on:
  workflow_dispatch:
    inputs:
      prompt:
        description: Prompt passed to claude -p
        required: true
        default: Summarize README.md
        type: string

jobs:
  headless:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Check out the repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - name: Install the Claude Code CLI
        run: npm install -g --prefix "${{ runner.temp }}/claude-code" @anthropic-ai/claude-code

      - name: Run claude -p and print the result field
        env:
          PATH: ${{ runner.temp }}/claude-code/bin:${{ env.PATH }}
          PROMPT: ${{ inputs.prompt }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
        run: bash scripts/claude-headless.sh "$PROMPT"

workflow_dispatch is the only trigger, so a pull request does not start the job. The prompt goes in through the environment, then into a quoted argument. The install line is the prefix install that produced a claude binary on this machine. A GitHub-hosted runner was not used. contents: read is the only permission. The script asks for Read and dontAsk, and it passes --bare only when ANTHROPIC_API_KEY is set.

The script’s live path is the call below. --from-json is the test switch. It does not call claude.

claude --bare -p "${prompt}" \
  --output-format json \
  --permission-mode dontAsk \
  --allowedTools 'Read'

That block runs only when the API key is set. The subscription-token branch is the same command without --bare. Notes on both files are in the template README.

npm i -g @anthropic-ai/claude-code --prefix /home/ubuntu/.nvm/versions/node/v22.23.4

2.1.316 (Claude Code)

error: unknown option '--not-a-real-flag'

--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable.

More on this topic lives under AI agents and tools.