Guide

Claude Code CLI and headless mode

Harrowtech.ai · last checked 13 October 2026

The Claude Code CLI is the claude command you type in a terminal. This page covers how to start it, how to run a single prompt without the chat screen, how to pipe text in, and how to pick up an earlier conversation.

If claude is not on your machine yet, start with how to install Claude Code and come back here once claude --version answers.

Harrowtech.ai is independent of Anthropic. Commands below were checked against Anthropic's documentation and run on Claude Code 2.1.296.

Starting Claude from the shell

Anthropic's CLI reference lists these forms. The ones people use daily are the first three.

`claude`	Starts an interactive session.
`claude "query"`	Starts an interactive session with a first prompt already sent.
`claude -p "query"`	Answers once, prints the reply and exits. This is print mode.
`cat logs.txt \| claude -p "explain"`	Processes piped text.
`claude -c`	Continues the most recent conversation in the current folder.
`claude -r "auth-refactor" "Finish this PR"`	Resumes a session by ID or name, then sends a prompt.
`claude update`	Updates to the latest version.

If you mistype a subcommand, Claude Code suggests the closest match and exits without starting a session.

Print mode: one prompt, no chat screen

Add -p (or --print) to run non-interactively. Anthropic's page for this calls it running Claude Code programmatically, and it is what most people mean by headless mode. The example below is from that page:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Claude Code exits with code 0 on success and a non-zero code when the run fails, so a script can branch on the result. Tested on Claude Code 2.1.296 on 13 October 2026: claude -p "Reply with the single word: pong" returned pong, and the shell prompt came back straight away.

Piping text in

Print mode reads standard input, so you can pass a file or another command's output through it and redirect the answer:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Piped input is capped at 10MB. Past that, Claude Code exits with an error and a non-zero status, and Anthropic suggests saving the content to a file and naming the path in your prompt. Another test that day piped in the line ERROR: disk full on /dev/sda1 and asked what was wrong. The reply said the disk was full.

Choosing the output format

--output-format takes three values in print mode:

text: plain text. This is the default.
json: one JSON object with the result, the session ID and metadata. It also includes total_cost_usd, which Anthropic describes as a client-side estimate that can differ from your bill.
stream-json: one JSON event per line, for live output. Anthropic's example adds --verbose and --include-partial-messages.

To read one field, pipe through jq:

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

For output that must match a shape, add --json-schema with a JSON Schema. The checked answer arrives in the structured_output field.

Permissions when nobody is watching

A -p run cannot stop and ask you. Anthropic gives two ways to say in advance what is allowed:

--allowedTools lists tools that run without a prompt, using permission rule syntax. "Bash(git diff *)" allows any command that starts with git diff. The space before the star matters.
--permission-mode sets a baseline. The CLI reference accepts default, acceptEdits, plan, auto, dontAsk and bypassPermissions, with manual as another name for default. Claude's own help text lists six, showing manual in place of default. dontAsk denies every call that would have prompted, which Anthropic suggests for locked-down CI runs.

Anthropic adds a warning worth acting on: a run where nothing sets a permission mode takes the built-in starting mode, which can be auto. So name the mode you want in every script rather than relying on the default.

Two limits are print-mode only: --max-turns caps the number of agentic turns and exits with an error when reached, and --max-budget-usd stops the run once estimated spend reaches an amount. That figure is a client-side estimate that can differ from your bill, and Anthropic notes spend can pass the cap, so leave headroom.

Print mode skips the workspace trust dialog. Anthropic's help text says to use it only in folders you trust, and its docs say a -p run still loads a project's hooks and MCP servers. For scripts, Anthropic recommends --bare, which skips hooks, skills, custom commands, subagents, plugins, MCP servers, auto memory and CLAUDE.md. Anthropic says bare mode will become the default for -p in a future release. Bare mode ignores your subscription login, so it needs ANTHROPIC_API_KEY. See Claude Code API key and login errors.

Resuming a conversation

A session you ran with -p can be continued with -p:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue

That second form was tested on 13 October 2026, and the follow-up knew what the first run had said. Anthropic's flag table adds one detail: plain claude --continue skips sessions created with claude -p, while claude -p --continue includes them.

With several conversations running, capture the session ID from the JSON output and resume it by ID:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

You can also name a session with -n and resume it with claude --resume <name>. --fork-session, used with --resume or --continue, starts a new session ID instead of reusing the old one. --no-session-persistence does the opposite for print mode: nothing is saved, so nothing can be resumed.

A few other flags

`--model`	Sets the model for this session, by alias such as `sonnet` or `opus`, or by full name.
`--add-dir`	Adds more folders Claude may read and edit.
`--append-system-prompt`	Adds your text to the end of the default system prompt. `--system-prompt` replaces the whole prompt instead.
`--tools`	Limits which built-in tools exist at all. `--allowedTools` only skips the prompt.
`--worktree`	Starts in an isolated git worktree.
`--debug-file`	Writes debug logs to a path you choose.

What this guide does not cover

It does not cover the Python and TypeScript Agent SDK packages, background sessions (--bg cannot be combined with -p), cloud sessions, or plugin commands. Anthropic notes that claude --help does not list every flag, and flags change between versions, so run claude --version and check the reference if one is missing.

Sources

Anthropic: CLI reference, read 13 October 2026.
Anthropic: Run Claude Code programmatically, read 13 October 2026.
Commands run on Claude Code 2.1.296 (Linux, WSL) on 13 October 2026, using claude --help and the examples marked as tested above.