164 lines
26 KiB
Markdown
164 lines
26 KiB
Markdown
> ## 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
|
|
|
|
| Command | Description | Example |
|
|
| :------------------------------ | :----------------------------------------------------------------- | :------------------------------------------------ |
|
|
| `claude` | Start interactive REPL | `claude` |
|
|
| `claude "query"` | Start REPL 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 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). |
|
|
|
|
## 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 (works in both interactive and print modes) | `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 (print mode only) | `claude -p --append-system-prompt-file ./extra-rules.txt "query"` |
|
|
| `--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 slash 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 (works in both interactive and print modes) | `claude --system-prompt "You are a Python expert"` |
|
|
| `--system-prompt-file` | Load system prompt from a file, replacing the default prompt (print mode only) | `claude -p --system-prompt-file ./custom-prompt.txt "query"` |
|
|
| `--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 (works in both interactive and print modes). 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 (helpful for debugging in both print and interactive modes) | `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 [`Task(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, each serving a different purpose:
|
|
|
|
| Flag | Behavior | Modes | Use Case |
|
|
| :---------------------------- | :------------------------------------------ | :------------------ | :------------------------------------------------------------------- |
|
|
| `--system-prompt` | **Replaces** entire default prompt | Interactive + Print | Complete control over Claude's behavior and instructions |
|
|
| `--system-prompt-file` | **Replaces** with file contents | Print only | Load prompts from files for reproducibility and version control |
|
|
| `--append-system-prompt` | **Appends** to default prompt | Interactive + Print | Add specific instructions while keeping default Claude Code behavior |
|
|
| `--append-system-prompt-file` | **Appends** file contents to default prompt | Print only | 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 -p --system-prompt-file ./prompts/code-review.txt "Review this PR"
|
|
```
|
|
|
|
* **`--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 -p --append-system-prompt-file ./prompts/style-rules.txt "Review this PR"
|
|
```
|
|
|
|
`--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
|