> ## Documentation Index
>
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Complete reference for Claude Code command-line interface, including commands and flags.

## CLI commands

You can start sessions, pipe content, resume conversations, and manage updates with these commands:

| Command                         | Description                                                                                                                                                                            | Example                                            |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| `claude`                        | Start interactive session                                                                                                                                                              | `claude`                                           |
| `claude "query"`                | Start interactive session with initial prompt                                                                                                                                          | `claude "explain this project"`                    |
| `claude -p "query"`             | Query via SDK, then exit                                                                                                                                                               | `claude -p "explain this function"`                |
| `cat file \| claude -p "query"` | Process piped content                                                                                                                                                                  | `cat logs.txt \| claude -p "explain"`              |
| `claude -c`                     | Continue most recent conversation in current directory                                                                                                                                 | `claude -c`                                        |
| `claude -c -p "query"`          | Continue via SDK                                                                                                                                                                       | `claude -c -p "Check for type errors"`             |
| `claude -r "<session>" "query"` | Resume session by ID or name                                                                                                                                                           | `claude -r "auth-refactor" "Finish this PR"`       |
| `claude update`                 | Update to latest version                                                                                                                                                               | `claude update`                                    |
| `claude auth login`             | Sign in to your Anthropic account. Use `--email` to pre-fill your email address and `--sso` to force SSO authentication                                                                | `claude auth login --email user@example.com --sso` |
| `claude auth logout`            | Log out from your Anthropic account                                                                                                                                                    | `claude auth logout`                               |
| `claude auth status`            | Show authentication status as JSON. Use `--text` for human-readable output. Exits with code 0 if logged in, 1 if not                                                                   | `claude auth status`                               |
| `claude agents`                 | List all configured [subagents](/en/sub-agents), grouped by source                                                                                                                     | `claude agents`                                    |
| `claude mcp`                    | Configure Model Context Protocol (MCP) servers                                                                                                                                         | See the [Claude Code MCP documentation](/en/mcp).  |
| `claude remote-control`         | Start a [Remote Control session](/en/remote-control) to control Claude Code from Claude.ai or the Claude app while running locally. See [Remote Control](/en/remote-control) for flags | `claude remote-control`                            |

## CLI flags

Customize Claude Code's behavior with these command-line flags:

| Flag                                   | Description                                                                                                                                                                                               | Example                                                                                            |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| `--add-dir`                            | Add additional working directories for Claude to access (validates each path exists as a directory)                                                                                                       | `claude --add-dir ../apps ../lib`                                                                  |
| `--agent`                              | Specify an agent for the current session (overrides the `agent` setting)                                                                                                                                  | `claude --agent my-custom-agent`                                                                   |
| `--agents`                             | Define custom [subagents](/en/sub-agents) dynamically via JSON (see below for format)                                                                                                                     | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |
| `--allow-dangerously-skip-permissions` | Enable permission bypassing as an option without immediately activating it. Allows composing with `--permission-mode` (use with caution)                                                                  | `claude --permission-mode plan --allow-dangerously-skip-permissions`                               |
| `--allowedTools`                       | Tools that execute without prompting for permission. See [permission rule syntax](/en/settings#permission-rule-syntax) for pattern matching. To restrict which tools are available, use `--tools` instead | `"Bash(git log *)" "Bash(git diff *)" "Read"`                                                      |
| `--append-system-prompt`               | Append custom text to the end of the default system prompt                                                                                                                                                | `claude --append-system-prompt "Always use TypeScript"`                                            |
| `--append-system-prompt-file`          | Load additional system prompt text from a file and append to the default prompt                                                                                                                           | `claude --append-system-prompt-file ./extra-rules.txt`                                             |
| `--betas`                              | Beta headers to include in API requests (API key users only)                                                                                                                                              | `claude --betas interleaved-thinking`                                                              |
| `--chrome`                             | Enable [Chrome browser integration](/en/chrome) for web automation and testing                                                                                                                            | `claude --chrome`                                                                                  |
| `--continue`, `-c`                     | Load the most recent conversation in the current directory                                                                                                                                                | `claude --continue`                                                                                |
| `--dangerously-skip-permissions`       | Skip all permission prompts (use with caution)                                                                                                                                                            | `claude --dangerously-skip-permissions`                                                            |
| `--debug`                              | Enable debug mode with optional category filtering (for example, `"api,hooks"` or `"!statsig,!file"`)                                                                                                     | `claude --debug "api,mcp"`                                                                         |
| `--disable-slash-commands`             | Disable all skills and commands for this session                                                                                                                                                          | `claude --disable-slash-commands`                                                                  |
| `--disallowedTools`                    | Tools that are removed from the model's context and cannot be used                                                                                                                                        | `"Bash(git log *)" "Bash(git diff *)" "Edit"`                                                      |
| `--fallback-model`                     | Enable automatic fallback to specified model when default model is overloaded (print mode only)                                                                                                           | `claude -p --fallback-model sonnet "query"`                                                        |
| `--fork-session`                       | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`)                                                                                              | `claude --resume abc123 --fork-session`                                                            |
| `--from-pr`                            | Resume sessions linked to a specific GitHub PR. Accepts a PR number or URL. Sessions are automatically linked when created via `gh pr create`                                                             | `claude --from-pr 123`                                                                             |
| `--ide`                                | Automatically connect to IDE on startup if exactly one valid IDE is available                                                                                                                             | `claude --ide`                                                                                     |
| `--init`                               | Run initialization hooks and start interactive mode                                                                                                                                                       | `claude --init`                                                                                    |
| `--init-only`                          | Run initialization hooks and exit (no interactive session)                                                                                                                                                | `claude --init-only`                                                                               |
| `--include-partial-messages`           | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`)                                                                                                         | `claude -p --output-format stream-json --include-partial-messages "query"`                         |
| `--input-format`                       | Specify input format for print mode (options: `text`, `stream-json`)                                                                                                                                      | `claude -p --output-format json --input-format stream-json`                                        |
| `--json-schema`                        | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [structured outputs](https://platform.claude.com/docs/en/agent-sdk/structured-outputs))         | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"`                           |
| `--maintenance`                        | Run maintenance hooks and exit                                                                                                                                                                            | `claude --maintenance`                                                                             |
| `--max-budget-usd`                     | Maximum dollar amount to spend on API calls before stopping (print mode only)                                                                                                                             | `claude -p --max-budget-usd 5.00 "query"`                                                          |
| `--max-turns`                          | Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default                                                                                   | `claude -p --max-turns 3 "query"`                                                                  |
| `--mcp-config`                         | Load MCP servers from JSON files or strings (space-separated)                                                                                                                                             | `claude --mcp-config ./mcp.json`                                                                   |
| `--model`                              | Sets the model for the current session with an alias for the latest model (`sonnet` or `opus`) or a model's full name                                                                                     | `claude --model claude-sonnet-4-6`                                                                 |
| `--no-chrome`                          | Disable [Chrome browser integration](/en/chrome) for this session                                                                                                                                         | `claude --no-chrome`                                                                               |
| `--no-session-persistence`             | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only)                                                                                                     | `claude -p --no-session-persistence "query"`                                                       |
| `--output-format`                      | Specify output format for print mode (options: `text`, `json`, `stream-json`)                                                                                                                             | `claude -p "query" --output-format json`                                                           |
| `--permission-mode`                    | Begin in a specified [permission mode](/en/permissions#permission-modes)                                                                                                                                  | `claude --permission-mode plan`                                                                    |
| `--permission-prompt-tool`             | Specify an MCP tool to handle permission prompts in non-interactive mode                                                                                                                                  | `claude -p --permission-prompt-tool mcp_auth_tool "query"`                                         |
| `--plugin-dir`                         | Load plugins from directories for this session only (repeatable)                                                                                                                                          | `claude --plugin-dir ./my-plugins`                                                                 |
| `--print`, `-p`                        | Print response without interactive mode (see [Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview) for programmatic usage details)                                            | `claude -p "query"`                                                                                |
| `--remote`                             | Create a new [web session](/en/claude-code-on-the-web) on claude.ai with the provided task description                                                                                                    | `claude --remote "Fix the login bug"`                                                              |
| `--resume`, `-r`                       | Resume a specific session by ID or name, or show an interactive picker to choose a session                                                                                                                | `claude --resume auth-refactor`                                                                    |
| `--session-id`                         | Use a specific session ID for the conversation (must be a valid UUID)                                                                                                                                     | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"`                                       |
| `--setting-sources`                    | Comma-separated list of setting sources to load (`user`, `project`, `local`)                                                                                                                              | `claude --setting-sources user,project`                                                            |
| `--settings`                           | Path to a settings JSON file or a JSON string to load additional settings from                                                                                                                            | `claude --settings ./settings.json`                                                                |
| `--strict-mcp-config`                  | Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations                                                                                                                           | `claude --strict-mcp-config --mcp-config ./mcp.json`                                               |
| `--system-prompt`                      | Replace the entire system prompt with custom text                                                                                                                                                         | `claude --system-prompt "You are a Python expert"`                                                 |
| `--system-prompt-file`                 | Load system prompt from a file, replacing the default prompt                                                                                                                                              | `claude --system-prompt-file ./custom-prompt.txt`                                                  |
| `--teleport`                           | Resume a [web session](/en/claude-code-on-the-web) in your local terminal                                                                                                                                 | `claude --teleport`                                                                                |
| `--teammate-mode`                      | Set how [agent team](/en/agent-teams) teammates display: `auto` (default), `in-process`, or `tmux`. See [set up agent teams](/en/agent-teams#set-up-agent-teams)                                          | `claude --teammate-mode in-process`                                                                |
| `--tools`                              | Restrict which built-in tools Claude can use. Use `""` to disable all, `"default"` for all, or tool names like `"Bash,Edit,Read"`                                                                         | `claude --tools "Bash,Edit,Read"`                                                                  |
| `--verbose`                            | Enable verbose logging, shows full turn-by-turn output                                                                                                                                                    | `claude --verbose`                                                                                 |
| `--version`, `-v`                      | Output the version number                                                                                                                                                                                 | `claude -v`                                                                                        |
| `--worktree`, `-w`                     | Start Claude in an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) at `<repo>/.claude/worktrees/<name>`. If no name is given, one is auto-generated    | `claude -w feature-auth`                                                                           |

<Tip>
  The `--output-format json` flag is particularly useful for scripting and
  automation, allowing you to parse Claude's responses programmatically.
</Tip>

### Agents flag format

The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:

| Field             | Required | Description                                                                                                                                                                                                         |
| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `description`     | Yes      | Natural language description of when the subagent should be invoked                                                                                                                                                 |
| `prompt`          | Yes      | The system prompt that guides the subagent's behavior                                                                                                                                                               |
| `tools`           | No       | Array of specific tools the subagent can use, for example `["Read", "Edit", "Bash"]`. If omitted, inherits all tools. Supports [`Agent(agent_type)`](/en/sub-agents#restrict-which-subagents-can-be-spawned) syntax |
| `disallowedTools` | No       | Array of tool names to explicitly deny for this subagent                                                                                                                                                            |
| `model`           | No       | Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit`                                                                                                                      |
| `skills`          | No       | Array of [skill](/en/skills) names to preload into the subagent's context                                                                                                                                           |
| `mcpServers`      | No       | Array of [MCP servers](/en/mcp) for this subagent. Each entry is a server name string or a `{name: config}` object                                                                                                  |
| `maxTurns`        | No       | Maximum number of agentic turns before the subagent stops                                                                                                                                                           |

Example:

```bash theme={null}
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'
```

For more details on creating and using subagents, see the [subagents documentation](/en/sub-agents).

### System prompt flags

Claude Code provides four flags for customizing the system prompt. All four work in both interactive and non-interactive modes.

| Flag                          | Behavior                                    | Use case                                                             |
| :---------------------------- | :------------------------------------------ | :------------------------------------------------------------------- |
| `--system-prompt`             | **Replaces** entire default prompt          | Complete control over Claude's behavior and instructions             |
| `--system-prompt-file`        | **Replaces** with file contents             | Load prompts from files for reproducibility and version control      |
| `--append-system-prompt`      | **Appends** to default prompt               | Add specific instructions while keeping default Claude Code behavior |
| `--append-system-prompt-file` | **Appends** file contents to default prompt | Load additional instructions from files while keeping defaults       |

**When to use each:**

- **`--system-prompt`**: use when you need complete control over Claude's system prompt. This removes all default Claude Code instructions, giving you a blank slate.

  ```bash theme={null}
  claude --system-prompt "You are a Python expert who only writes type-annotated code"
  ```

- **`--system-prompt-file`**: use when you want to load a custom prompt from a file, useful for team consistency or version-controlled prompt templates.

  ```bash theme={null}
  claude --system-prompt-file ./prompts/code-review.txt
  ```

- **`--append-system-prompt`**: use when you want to add specific instructions while keeping Claude Code's default capabilities intact. This is the safest option for most use cases.

  ```bash theme={null}
  claude --append-system-prompt "Always use TypeScript and include JSDoc comments"
  ```

- **`--append-system-prompt-file`**: use when you want to append instructions from a file while keeping Claude Code's defaults. Useful for version-controlled additions.
  ```bash theme={null}
  claude --append-system-prompt-file ./prompts/style-rules.txt
  ```

`--system-prompt` and `--system-prompt-file` are mutually exclusive. The append flags can be used together with either replacement flag.

For most use cases, `--append-system-prompt` or `--append-system-prompt-file` is recommended as they preserve Claude Code's built-in capabilities while adding your custom requirements. Use `--system-prompt` or `--system-prompt-file` only when you need complete control over the system prompt.

## See also

- [Chrome extension](/en/chrome) - Browser automation and web testing
- [Interactive mode](/en/interactive-mode) - Shortcuts, input modes, and interactive features
- [Quickstart guide](/en/quickstart) - Getting started with Claude Code
- [Common workflows](/en/common-workflows) - Advanced workflows and patterns
- [Settings](/en/settings) - Configuration options
- [Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview) - Programmatic usage and integrations
