wikis / Claude Code / wiki / concepts / cli-reference.md view as markdown

CLI Reference: Commands, Flags, and Print Mode

Definition

The claude binary is both an interactive REPL launcher and a scriptable non-interactive tool. This page covers the CLI commands and flags, non-interactive ("print") mode with -p, session resume, and structured JSON output for pipelines.

How It Works

Core commands

Mistyped subcommands get a suggestion (claude udpate → Did you mean claude update?). claude --help does not list every flag.

Essential flags

• Sessions: --continue/-c, --resume/-r (ID, name, or interactive picker), --fork-session (new session ID when resuming), --session-id <uuid>, --name/-n (display name, resumable by name), --from-pr 123 (resume sessions linked to a PR)
• Models: --model (alias sonnet/opus/haiku/fable or full name), --effort low|medium|high|xhigh|max, --fallback-model sonnet,haiku
• Permissions: --permission-mode (default, acceptEdits, plan, auto, dontAsk, bypassPermissions), --allowedTools, --disallowedTools, --tools "Bash,Edit,Read" (restrict available built-ins), --dangerously-skip-permissions
• Context/config: --add-dir, --settings <file-or-json>, --setting-sources user,project,local, --mcp-config ./mcp.json, --strict-mcp-config, --agents '<json>', --plugin-dir ./my-plugin
• System prompt: --system-prompt / --system-prompt-file (replace; mutually exclusive with each other) and --append-system-prompt / --append-system-prompt-file (append; combinable with either). Append when Claude should stay a coding assistant with extra rules; replace only when you take responsibility for tool guidance and safety instructions yourself.
• Diagnostics: --debug "api,mcp", --debug-file /tmp/claude-debug.log, --safe-mode (v2.1.169+, all customizations off), --verbose, --version/-v
• Isolation: --worktree/-w (git worktree at <repo>/.claude/worktrees/<name>), --bg (start as background agent)

Print mode (-p) for scripts and CI

All CLI options work with -p. The recommended pattern for scripted calls is bare mode:

claude --bare -p "Summarize this file" --allowedTools "Read"

--bare skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md, so runs are fast and reproducible across machines; pass any context you need explicitly (--settings, --mcp-config, --agents, --plugin-dir, --append-system-prompt). Bare mode skips OAuth/keychain reads — authenticate with ANTHROPIC_API_KEY or an apiKeyHelper.

Print-mode-only guardrails: --max-turns 3, --max-budget-usd 5.00, --no-session-persistence.

Structured output

--output-format accepts text (default), json (result, session ID, metadata including total_cost_usd), and stream-json (newline-delimited events). For schema-validated output:

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"]}'

The validated payload lands in the structured_output field; extract with jq '.structured_output' or the text result with jq -r '.result'. For token-level streaming, combine --output-format stream-json --verbose --include-partial-messages. The stream includes system/init (model, tools, plugins, plugin_errors) and system/api_retry events for CI failure handling.

Resume in pipelines

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

Or chain with --continue: claude -p "Now focus on the database queries" --continue.

Key Parameters

Permission rule syntax in --allowedTools uses prefix matching with a trailing *:

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 *)"

The space before * matters: Bash(git diff*) would also match git diff-index. acceptEdits mode auto-approves file writes plus common filesystem commands (mkdir, touch, mv, cp); dontAsk denies anything not pre-approved — useful for locked-down CI, where an unapproved tool call aborts the run.

When To Use

• Interactive development: plain claude; see interactive mode.
• One-shot queries, lint bots, commit generators, CI checks: claude --bare -p with explicit --allowedTools and --output-format json.
• Long-lived programmatic control (callbacks, message objects, structured streaming): use the agent sdk instead of shelling out.
• Parallel/background work: --bg, claude agents, --worktree (see subagents orchestration).

Risks & Pitfalls

• Without --bare, claude -p loads the same context an interactive session would — a teammate's ~/.claude hook or a project .mcp.json can change script behavior between machines.
• Interactive-dialog commands (/config, /login) are unavailable in -p mode; user-invoked skills do work by including /skill-name in the prompt string.
• Piped stdin over 10MB exits non-zero; write large inputs to a file and reference the path.
• Background bash tasks started during a -p run are terminated ~5 seconds after the final result (v2.1.163+).
• Starting June 15, 2026, Agent SDK and claude -p usage on subscription plans draws from a separate monthly Agent SDK credit — relevant for cost management.

Related Concepts

• interactive mode — the REPL side: slash commands and shortcuts
• agent sdk — Python/TypeScript packages built on the same engine
• permissions security — full permission rule and mode semantics
• configuration — --settings interplay with settings files
• github actions and gitlab cicd — CI integrations using print mode

Sources

• raw/llms_txt_doc-cli-reference.md — complete command and flag tables, system-prompt flag guidance
• raw/llms_txt_doc-run-claude-code-programmatically.md — -p patterns, bare mode, structured output, streaming events, resume