---
title: "CLI Reference: Commands, Flags, and Print Mode"
type: concept
tags: [cli, automation, headless, scripting, foundational]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-cli-reference.md", "raw/llms_txt_doc-run-claude-code-programmatically.md"]
---

# 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

| Command | What it does |
| --- | --- |
| `claude` | Start interactive session |
| `claude "query"` | Start interactive session with initial prompt |
| `claude -p "query"` | Query non-interactively, print result, exit |
| `cat file | claude -p "query"` | Process piped content (stdin capped at 10MB as of v2.1.128) |
| `claude -c` | Continue most recent conversation in current directory |
| `claude -r "<session>" "query"` | Resume session by ID or name |
| `claude update` / `claude install [version]` | Update or install/reinstall (`stable`, `latest`, or e.g. `2.1.118`) |
| `claude auth login` / `logout` / `status` | Authentication management |
| `claude mcp` | Configure MCP servers |
| `claude plugin` | Manage plugins (e.g. `claude plugin install code-review@claude-plugins-official`) |
| `claude setup-token` | Generate a long-lived OAuth token for CI |
| `claude agents` / `attach <id>` / `logs <id>` / `stop <id>` / `respawn <id>` / `rm <id>` | Background-session management |
| `claude project purge [path]` | Delete local state for a project (`--dry-run` to preview) |
| `claude auto-mode defaults` / `config` / `critique` | Inspect auto-mode classifier rules |

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**:

```bash
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:

```bash
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

```bash
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 ` *`:

```bash
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 [[concepts/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 [[concepts/agent-sdk]] instead of shelling out.
- Parallel/background work: `--bg`, `claude agents`, `--worktree` (see [[concepts/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 [[syntheses/cost-management]].

## Related Concepts

- [[concepts/interactive-mode]] — the REPL side: slash commands and shortcuts
- [[concepts/agent-sdk]] — Python/TypeScript packages built on the same engine
- [[concepts/permissions-security]] — full permission rule and mode semantics
- [[concepts/configuration]] — `--settings` interplay with settings files
- [[entities/github-actions]] and [[entities/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