OPERATOR GUIDE / 2.1.220

The Complete Claude Code CLI Guide

A practical route through Claude Code: choose the right execution mode, preserve context, control authority, connect tools, and verify what actually loaded.

Open the exhaustive reference →
00

Route map

01

Choose an execution mode

Interactive for collaborative work; print mode for bounded automation; background mode for work that should keep running.

02

Preserve session continuity

Continue the newest project session, resume by ID or name, and attach to background work without losing its transcript.

03

Set an authority boundary

Permission mode, allowed tools, sandbox settings, and safe mode determine what the agent may do.

04

Connect MCP deliberately

Pick the configuration scope, inspect approval and health, then authenticate remote servers separately.

05

Compose plugins, skills, and hooks

Plugins distribute components; skills teach workflows; hooks observe or gate lifecycle events.

06

Operate agents and diagnose drift

Monitor background sessions, inspect logs, and use doctor and the source ledger before assuming behavior.

01

CHAPTER / 01

Execution modes

The same executable supports three distinct operating styles. Keep the choice explicit because output shape, persistence, and permission behavior differ.
Manifest command
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
Relevant flags
-p, --print

Print a non-interactive response and exit.

none
--background, --bg

Control Claude Code background behavior.

none
--output-format

Select print-mode output: text, json, or stream-json.

none
Manifest playbook

Run Claude Code headlessly

Use print mode with bounded turns, structured output, and explicit permissions for scripts and CI.

  1. STEP 01 Start with a bounded text run claude -p --max-turns 8 "Review the current diff"

    Print mode writes the final response and exits.

  2. STEP 02 Request machine-readable output claude -p --output-format json --json-schema '{"type":"object"}' "Summarize the diff"

    JSON output and a schema make downstream parsing explicit.

  3. STEP 03 Grant only required tools claude -p --allowed-tools "Read" "Grep" "Bash(git diff *)" "Review this change"

    Narrow permission rules keep automation bounded.

02

CHAPTER / 02

Session continuity

Session state is a first-class asset. Name important sessions, resume them intentionally, and distinguish attach from restart or deletion.
Manifest command
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
claude attach runtime-confirmed

Attach this terminal to a background session.

claude logs runtime-confirmed

Print recent terminal output for a background session.

Relevant flags
-c, --continue

Continue the most recent conversation in the current directory.

none
-r, --resume

Resume a session by ID or name, or open the session picker.

none
-n, --name

Name the session.

none
Manifest playbook

Continue or resume a session

Continue the latest conversation, resume a named session, or attach to a background session.

  1. STEP 01 Continue the latest project session claude --continue

    Loads the most recent conversation associated with this directory.

  2. STEP 02 Resume a named session claude --resume auth-refactor

    Resumes by session ID or user-assigned name.

  3. STEP 03 Attach to a background session claude attach 7c5dcf5d

    Connects the current terminal while the session keeps running.

03

CHAPTER / 03

Permissions and safe operation

Start from the least authority that can complete the job. A bypass flag is an exceptional high-risk boundary, not a convenience default.
Manifest command
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
Relevant flags
--permission-mode

Start in a selected permission mode.

review
--allowed-tools, --allowedTools

Grant matching tools without a permission prompt.

review
--safe-mode

Control Claude Code safe mode behavior.

none
--dangerously-skip-permissions

Control Claude Code dangerously skip permissions behavior.

high
Manifest playbook

Design permission boundaries

Choose a permission mode, add narrow allow rules, and keep bypass mode visibly high risk.

  1. STEP 01 Start in plan mode claude --permission-mode plan

    Plan mode supports repository analysis before edits.

  2. STEP 02 Allow specific read-only commands claude --allowed-tools "Read" "Grep" "Bash(git diff *)"

    Tool-pattern rules are safer than broad shell access.

  3. STEP 03 Troubleshoot customizations safely claude --safe-mode

    Safe mode disables project customizations, hooks, plugins, skills, and MCP.

04

CHAPTER / 04

MCP: tools beyond the terminal

An MCP server can add tools, resources, and prompts. Configuration scope and project approval are separate from OAuth authentication.
Manifest command
claude mcp add runtime-confirmed

Add a stdio, SSE, or HTTP MCP server.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp get runtime-confirmed

Inspect one configured MCP server and its approval state.

claude mcp get sentry
claude mcp login runtime-confirmed

Run the OAuth flow for a configured remote MCP server.

claude mcp login sentry --no-browser
claude mcp serve runtime-confirmed

Expose Claude Code tools as a local stdio MCP server.

claude mcp serve
Manifest playbook

Add and authenticate an MCP server

Register a server at the intended scope, inspect it, and run OAuth separately when required.

  1. STEP 01 Add a remote server claude mcp add --transport http sentry https://mcp.sentry.dev/mcp --scope user

    Choose local, user, or project scope deliberately.

  2. STEP 02 Inspect approval and health claude mcp get sentry

    Unapproved project servers remain pending and are not connected.

  3. STEP 03 Authenticate over SSH claude mcp login sentry --no-browser

    Prints an authorization URL rather than opening a browser.

05

CHAPTER / 05

Plugins, skills, and hooks

A plugin can package skills, commands, agents, hooks, and MCP configuration. Inspect the loaded components after installation.
Manifest command
claude plugin marketplace add runtime-confirmed

Register a plugin marketplace source.

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install runtime-confirmed

Install a plugin from a configured marketplace.

claude plugin install code-review@claude-plugins-official
claude plugin details runtime-confirmed

Show a plugin component inventory and projected token cost.

claude plugin details code-review
claude plugin validate runtime-confirmed

Validate plugin structure and metadata.

claude plugin validate ./my-plugin --strict
Relevant flags
--plugin-dir

Load plugins from directories for this session.

review
Manifest playbook

Install plugins and inspect skills and hooks

Add a trusted marketplace, install at a scope, then inspect the loaded skills and hooks in-session.

  1. STEP 01 Add a marketplace claude plugin marketplace add anthropics/claude-plugins-official

    Marketplace sources determine which plugins are installable.

  2. STEP 02 Install at project scope claude plugin install code-review@claude-plugins-official --scope project

    Project scope shares plugin policy with the repository.

  3. STEP 03 Inspect runtime components

    Use /skills, /hooks, and /plugin inside Claude Code to verify what loaded.

06

CHAPTER / 06

Agents and background work

Background sessions let work continue while agent view and logs provide an operational control plane.
Manifest command
claude agents runtime-confirmed

Open agent view or query active background sessions.

claude agents --json
claude logs runtime-confirmed

Print recent terminal output for a background session.

claude stop runtime-confirmed

Stop a background session while retaining its conversation.

claude respawn runtime-confirmed

Restart a background session with its conversation intact.

Relevant flags
--agent

Use a named agent for this session.

review
--agents

Define session subagents with a JSON object.

review
--background, --bg

Control Claude Code background behavior.

none
Manifest playbook

Launch and monitor agents

Define a session agent, start work in the background, and inspect active sessions as JSON.

  1. STEP 01 Start a named agent in the background claude --background --agent reviewer "Review the current branch"

    The command returns a session ID for later management.

  2. STEP 02 List active agents claude agents --json

    JSON mode supports external monitoring and orchestration.

  3. STEP 03 Read recent output claude logs 7c5dcf5d

    Inspect progress without attaching to the session.

07

CHAPTER / 07

Headless automation

Print mode is designed for scripts. Bound turns and cost, select output format, and grant only the tools the job requires.
Manifest command
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
Relevant flags
-p, --print

Print a non-interactive response and exit.

none
--max-turns

Limit agentic turns in print mode.

none
--max-budget-usd

Stop print-mode execution at an approximate dollar budget.

none
--json-schema

Validate print-mode structured output against a JSON Schema.

none
--input-format

Select print-mode input: text or stream-json.

none
--output-format

Select print-mode output: text, json, or stream-json.

none
Manifest playbook

Run Claude Code headlessly

Use print mode with bounded turns, structured output, and explicit permissions for scripts and CI.

  1. STEP 01 Start with a bounded text run claude -p --max-turns 8 "Review the current diff"

    Print mode writes the final response and exits.

  2. STEP 02 Request machine-readable output claude -p --output-format json --json-schema '{"type":"object"}' "Summarize the diff"

    JSON output and a schema make downstream parsing explicit.

  3. STEP 03 Grant only required tools claude -p --allowed-tools "Read" "Grep" "Bash(git diff *)" "Review this change"

    Narrow permission rules keep automation bounded.

08

CHAPTER / 08

Read the evidence labels

A missing flag in root help does not prove it is unavailable, and a documented feature is not automatically present on every platform or plan.
runtime-confirmed Installed release
docs-confirmed Official docs
conditional Conditional
source-preview Public asset preview
historical Historical only
Operating principle
  1. Prefer explicit scope over ambient configuration.
  2. Treat transcripts, settings, and credentials as different state domains.
  3. Verify loaded tools and permissions before unattended execution.
  4. Use source and availability labels when release help and documentation drift.
SOURCE 01 Claude Code 2.1.220 recursive local help runtime-help / release SOURCE 02 Official Claude Code CLI reference official-docs / reference SOURCE 03 Official Claude Code commands reference official-docs / reference SOURCE 04 Official Claude Code settings reference official-docs / reference SOURCE 05 Published Claude Code settings JSON Schema json-schema / reference SOURCE 06 Official Claude Code environment variables reference official-docs / reference SOURCE 07 Public Claude Code v2.1.220 plugin assets official-source / preview SOURCE 08 @anthropic-ai/claude-code 2.1.220 package metadata package-metadata / reference