mirror of
https://github.com/nicepkg/ai-workflow.git
synced 2026-11-18 18:04:23 +00:00
148 lines
12 KiB
Markdown
148 lines
12 KiB
Markdown
---
|
||
source: https://code.claude.com/docs/en/cli-reference
|
||
title: CLI reference
|
||
---
|
||
|
||
## [](#cli-commands) 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 mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/docs/en/mcp). |
|
||
|
||
## [](#cli-flags) 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](/docs/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](/docs/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](/docs/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` |
|
||
| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` |
|
||
| `--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 [Agent SDK Structured Outputs](https://docs.claude.com/en/docs/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |
|
||
| `--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-5-20250929` |
|
||
| `--no-chrome` | Disable [Chrome browser integration](/docs/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](/docs/en/iam#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 [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) for programmatic usage details) | `claude -p "query"` |
|
||
| `--remote` | Create a new [web session](/docs/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](/docs/en/claude-code-on-the-web) in your local terminal | `claude --teleport` |
|
||
| `--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` |
|
||
|
||
The `--output-format json` flag is particularly useful for scripting and
|
||
automation, allowing you to parse Claude’s responses programmatically.
|
||
|
||
### [](#agents-flag-format) 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 |
|
||
| `model` | No | Model alias to use: `sonnet`, `opus`, or `haiku`. If omitted, uses the default subagent model |
|
||
|
||
Example:
|
||
|
||
```bash
|
||
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](/docs/en/sub-agents).
|
||
|
||
### [](#system-prompt-flags) 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
|
||
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
|
||
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
|
||
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
|
||
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) See also
|
||
|
||
- [Chrome extension](/docs/en/chrome) - Browser automation and web testing
|
||
- [Interactive mode](/docs/en/interactive-mode) - Shortcuts, input modes, and interactive features
|
||
- [Slash commands](/docs/en/slash-commands) - Interactive session commands
|
||
- [Quickstart guide](/docs/en/quickstart) - Getting started with Claude Code
|
||
- [Common workflows](/docs/en/common-workflows) - Advanced workflows and patterns
|
||
- [Settings](/docs/en/settings) - Configuration options
|
||
- [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) - Programmatic usage and integrations |