The Headless/Streaming Flag Set
AdvancedDistinguish Claude Code's session and operating-mode features · Difficulty 1/5
Explanation
Beyond the Bare `claude -p`
claude -p "..." is the example that comes up first for headless mode, but it's shorthand for a small, specific flag set worth knowing individually -- each flag controls a different axis of how a non-interactive run behaves.
| Flag | What it controls |
|---|---|
--print / -p | Non-interactive, headless output -- process the prompt, print the result, exit. No TUI. |
--output-format | Selects the structured output format (e.g., stream-JSON) for programmatic consumption instead of plain text |
--resume | Reattaches to a specific prior session and continues it |
--continue | Continues the most recent session without needing to specify a session ID |
Why the Distinctions Matter
--print/-p alone answers *whether* the run is interactive at all -- it's the flag that makes headless mode headless. --output-format is a separate, composable choice layered on top: a headless run can emit plain text, or it can emit structured stream-JSON that a calling script parses incrementally instead of waiting for one final blob. This is the same headless/streaming independence covered elsewhere in this lesson -- -p and --output-format are two different dials, not one setting.
--resume and --continue solve a different problem: session continuity across separate invocations. A CI job or script that needs to pick back up on a specific earlier session uses --resume (naming that session); a script that just wants "whatever I was doing last" uses --continue. Neither of these is about interactivity or output format -- they're about which conversation state the new invocation attaches to.
Common exam traps
- Treating
--output-formatas a synonym for-p/--print.-pcontrols interactivity;--output-formatcontrols the shape of what gets printed once you're already non-interactive. A scenario can combine both (headless + stream-JSON) or use-palone (headless + plain text). - Confusing
--resume(reattach to a specific named session) with--continue(continue the most recent session without specifying one) -- both address session continuity, but they answer different questions about which session to pick up.
Key Takeaways
- --print / -p runs Claude Code non-interactively (headless), printing output and exiting with no TUI
- --output-format selects structured output (e.g., stream-JSON) for programmatic consumption, independent of whether the run is headless
- --resume reattaches to a specific prior session; --continue continues the most recent session without naming one
- -p (interactivity) and --output-format (output shape) are separate, composable flags, not the same setting
Glossary Terms
Claude Code CLI flag for non-interactive (headless) execution. Processes the prompt, outputs to stdout, and exits immediately without entering an interactive session. Essential for CI/CD pipeline integration, scripting, and automation workflows.
A Claude Code CLI flag that controls the response format. Values: 'text' (default, plain text), 'json' (structured JSON), 'stream-json' (streaming JSON events). Use with --json-schema to guarantee output matches a specific schema. Critical for CI/CD pipeline integration.
Related Concepts