Skip to content
Home › Claude Code Configuration & Workflows

CI CD Headless Flags

Claude Code Configuration & Workflows

Definition

The CLI flags that run Claude Code non-interactively (headless) for CI/CD pipelines and scripting, controlling output format, tool access, turns, budget, and system prompt.

Key points

  • Headless: --print/-p runs one-shot without the interactive UI.
  • Output/input format: --output-format text|json|stream-json; --input-format text|stream-json.
  • Schema validation: --json-schema '{}' validates output against a JSON Schema (print mode) — see Structured outputs.
  • System prompt: --append-system-prompt adds to defaults; --system-prompt replaces them (dropping the default prompt). --bare skips hooks/skills/MCP/CLAUDE.md; --exclude-dynamic-system-prompt-sections aids CI cache reuse.
  • Tools: --allowedTools/--allowed-tools (execute without prompt, e.g. "Bash(git log *)" "Read"); --disallowedTools (bare name removes from context; scoped Bash(rm *) denies only matches); --tools restricts availability. Feeds the same model as permissions.
  • Limits/mode: --max-turns N (print mode only; errors at the limit); --max-budget-usd N; --permission-mode default|acceptEdits|plan|auto|dontAsk|bypassPermissions|manual; --model alias or full ID (overrides ANTHROPIC_MODEL).
  • Session: --resume/-r, --continue/-c, --fork-session, --add-dir — see Session Resume And Fork.
  • SDK equivalents: permission_mode/permissionMode, max_turns/maxTurns.

Why it matters for the exam

  • D3 (20%) and the "Claude Code for CI" scenario (D3+D4) test these flags directly — especially --append-system-prompt vs --system-prompt, --output-format, --json-schema, and --max-turns.

Common gotchas

  • --append-system-prompt adds; --system-prompt replaces and drops the default prompt — a classic distractor pair.
  • --max-turns works only in print mode and errors when the limit is hit (it does not silently stop).
  • --disallowedTools with a bare name removes the tool from context; a scoped pattern only denies matches.

See also

Sources

Referenced by