AX-Copilot/docs/claude-code-docs-main/en/reference/commands/cli-flags.md

Documentation Index

Fetch the complete documentation index at: https://vineetagarwal-code-claude-code.mintlify.app/llms.txt Use this file to discover all available pages before exploring further.

CLI flags

All options you can pass when launching Claude Code from the terminal. Run claude --help to see the full list.

Pass CLI flags when you launch Claude Code:

claude [flags] [prompt]

Run claude --help to see all available flags in your installed version.

Flags that configure session behavior (like `--model` and `--permission-mode`) can also be changed mid-session with the corresponding slash commands: `/model` and `/permissions`.

---

Core flags

Run Claude non-interactively. Claude processes the prompt (from the argument or stdin), prints the response, and exits. No REPL is started.

```bash  theme={null}
claude -p "explain the main function in src/index.ts"
echo "what does this do?" | claude -p
```

<Warning>
  The workspace trust dialog is skipped in `--print` mode. Only use this flag in directories you trust.
</Warning>

Works with: `--output-format`, `--model`, `--system-prompt`, `--permission-mode`, `--max-turns`, `--allowed-tools`.

Set the output format. Only works with `--print`.

| Value         | Description                                         |
| ------------- | --------------------------------------------------- |
| `text`        | Plain text output (default)                         |
| `json`        | Single JSON object with the complete result         |
| `stream-json` | Newline-delimited JSON stream with real-time events |

```bash  theme={null}
claude -p "list the exported functions" --output-format json
claude -p "refactor this file" --output-format stream-json
```

Use `stream-json` when you want to process Claude's output incrementally as it arrives (useful for long-running tasks or piping into other tools).

Set the input format for stdin. Only works with `--print`.

| Value         | Description                         |
| ------------- | ----------------------------------- |
| `text`        | Plain text input (default)          |
| `stream-json` | Newline-delimited JSON stream input |

`stream-json` input requires `--output-format stream-json`.

```bash  theme={null}
cat messages.jsonl | claude -p --input-format stream-json --output-format stream-json
```

Enable verbose output. Overrides the `verbose` setting in your config file.

```bash  theme={null}
claude --verbose
claude -p "debug this" --verbose
```

Print the version number and exit.

```bash  theme={null}
claude --version
claude -v
```

Display help for the command and exit.

```bash  theme={null}
claude --help
claude mcp --help
```

---

Session continuation flags

Resume the most recent conversation in the current directory without prompting for a session to resume.

```bash  theme={null}
claude --continue
claude -c "now add tests for that"
```

Resume a conversation by session ID. Without a value, opens an interactive picker where you can search through past sessions. Accepts an optional search term to filter the list.

```bash  theme={null}
# Open interactive picker
claude --resume

# Resume by session ID
claude --resume 550e8400-e29b-41d4-a716-446655440000

# Open picker filtered by search term
claude --resume "auth refactor"
```

When used with `--continue` or `--resume`, creates a new session branched from the resumed conversation rather than continuing it in place.

```bash  theme={null}
claude --resume <session-id> --fork-session
```

Set a display name for the session. The name appears in `/resume` and in the terminal title.

```bash  theme={null}
claude --name "auth-refactor"
```

Use a specific UUID as the session ID instead of a generated one. Must be a valid UUID. Cannot be used with `--continue` or `--resume` unless `--fork-session` is also specified.

```bash  theme={null}
claude --session-id 550e8400-e29b-41d4-a716-446655440000
```

Disable session persistence. The session will not be saved to disk and cannot be resumed. Only works with `--print`.

```bash  theme={null}
claude -p "one-off task" --no-session-persistence
```

---

Model and capability flags

Set the model for the session. Accepts an alias (e.g. `sonnet`, `opus`, `haiku`) or a full model ID (e.g. `claude-sonnet-4-6`).

```bash  theme={null}
claude --model sonnet
claude --model opus
claude --model claude-sonnet-4-6
```

You can also change the model mid-session with `/model`.

Set the effort level for the session. Controls how much computation Claude applies to each response.

| Value    | Description               |
| -------- | ------------------------- |
| `low`    | Faster, lighter responses |
| `medium` | Balanced (default)        |
| `high`   | More thorough reasoning   |
| `max`    | Maximum effort            |

```bash  theme={null}
claude --effort high "review this architecture"
```

Enable automatic fallback to a different model when the primary model is overloaded. Only works with `--print`.

```bash  theme={null}
claude -p "analyze this" --model opus --fallback-model sonnet
```

---

Permission and safety flags

Set the permission mode for the session.

| Mode                | Behavior                                                                             |
| ------------------- | ------------------------------------------------------------------------------------ |
| `default`           | Claude prompts before running commands and making edits                              |
| `acceptEdits`       | File edits are applied automatically; shell commands still require approval          |
| `plan`              | Claude proposes a plan and waits for your approval before acting                     |
| `bypassPermissions` | All actions run without prompts — intended for sandboxed automated environments only |

```bash  theme={null}
claude --permission-mode acceptEdits
claude --permission-mode plan "refactor the payment module"
claude --permission-mode bypassPermissions   # only in isolated sandboxes
```

<Warning>
  `bypassPermissions` disables all confirmation prompts. Only use it inside Docker containers, CI sandboxes, or other isolated environments with no internet access.
</Warning>

Bypass all permission checks. Claude takes all actions (file edits, shell commands) without asking. Equivalent to `--permission-mode bypassPermissions`.

```bash  theme={null}
claude --dangerously-skip-permissions -p "run the full test suite and fix failures"
```

<Warning>
  Only use this in sandboxed environments with no internet access. Claude Code enforces this: the flag is rejected when running with root/sudo privileges, or outside a Docker or bubblewrap container.
</Warning>

Make bypassing all permission checks available as an option during the session, without enabling it by default. Useful for automated pipelines that may need to escalate mid-session.

```bash  theme={null}
claude --allow-dangerously-skip-permissions -p "..."
```

**Aliases:** `--allowedTools`

Comma- or space-separated list of tools Claude is allowed to use. Tools not in this list are blocked.

```bash  theme={null}
claude --allowed-tools "Bash(git:*) Edit Read"
claude --allowed-tools Bash,Edit,Read
```

Tool patterns support glob-style matching: `Bash(git:*)` permits any git command; `Edit(src/**)` permits edits under `src/`.

**Aliases:** `--disallowedTools`

Comma- or space-separated list of tools Claude is not allowed to use.

```bash  theme={null}
claude --disallowed-tools "Bash(rm:*)"
```

Specify the exact set of built-in tools available for the session. Use `""` to disable all tools, `default` to enable all tools, or name specific tools.

```bash  theme={null}
# Disable all tools
claude --tools ""

# Enable only Bash and Read
claude --tools "Bash Read"

# Enable the default set
claude --tools default
```

---

Context and prompt flags

Add one or more directories to the tool access context. Claude will be able to read and edit files in these directories in addition to the current working directory.

```bash  theme={null}
claude --add-dir /shared/libs --add-dir /shared/config
```

Useful for monorepos or projects where related code lives outside the current directory.

Override the default system prompt with a custom prompt. Cannot be used with `--system-prompt-file`.

```bash  theme={null}
claude --system-prompt "You are a security auditor. Focus only on vulnerabilities."
```

Append text to the default system prompt. Unlike `--system-prompt`, this preserves Claude's built-in instructions and adds to them.

```bash  theme={null}
claude --append-system-prompt "Always suggest test cases for every function you write."
```

Load MCP servers from one or more JSON config files or inline JSON strings. Multiple values are space-separated.

```bash  theme={null}
# Load from a file
claude --mcp-config ./mcp-servers.json

# Load from multiple files
claude --mcp-config ./local-tools.json ./db-tools.json

# Pass inline JSON
claude --mcp-config '{"mcpServers":{"filesystem":{"command":"npx","args":["@modelcontextprotocol/server-filesystem","/tmp"]}}}'
```

See the [MCP servers guide](/guides/mcp-servers) for the config file format.

Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations (user config, project config, etc.).

```bash  theme={null}
claude --mcp-config ./ci-tools.json --strict-mcp-config
```

Load additional settings from a JSON file path or an inline JSON string.

```bash  theme={null}
# From a file
claude --settings ./team-settings.json

# Inline JSON
claude --settings '{"model":"claude-sonnet-4-6","verbose":true}'
```

Comma-separated list of settings sources to load. Controls which settings files are read at startup.

| Value     | Description                                                 |
| --------- | ----------------------------------------------------------- |
| `user`    | Load `~/.claude/settings.json`                              |
| `project` | Load `.claude/settings.json` in the current directory       |
| `local`   | Load `.claude/settings.local.json` in the current directory |

```bash  theme={null}
# Load only user-level settings (ignore project settings)
claude --setting-sources user

# Load user and project settings
claude --setting-sources user,project
```

Define custom agents inline as a JSON object. Each key is the agent name; the value is an object with `description` and `prompt`.

```bash  theme={null}
claude --agents '{"reviewer":{"description":"Reviews code for security issues","prompt":"You are a security-focused code reviewer."}}'
```

---

Output control flags

Include all hook lifecycle events in the output stream. Only works with `--output-format stream-json`.

```bash  theme={null}
claude -p "run task" --output-format stream-json --include-hook-events
```

Limit the number of agentic turns in non-interactive mode. Claude stops after this many turns even if the task is incomplete. Only works with `--print`.

```bash  theme={null}
claude -p "refactor this module" --max-turns 10
```

Set a maximum dollar amount to spend on API calls. Claude stops when the budget is reached. Only works with `--print`.

```bash  theme={null}
claude -p "large analysis task" --max-budget-usd 2.50
```

Provide a JSON Schema for structured output validation. Claude's response will be validated against this schema.

```bash  theme={null}
claude -p "extract the function names" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
```

---

Worktree flags

Create a new git worktree for this session. Optionally specify a name for the worktree branch. Accepts a PR number or GitHub PR URL to create a worktree from that PR.

```bash  theme={null}
claude --worktree
claude --worktree feature-auth
claude --worktree "#142"
```

Create a tmux session alongside the worktree. Requires `--worktree`. Uses iTerm2 native panes when available; pass `--tmux=classic` to force standard tmux behavior.

```bash  theme={null}
claude --worktree feature-auth --tmux
```

---

Debug flags

Enable debug mode. Optionally pass a filter to restrict which debug categories are shown.

```bash  theme={null}
# Show all debug output
claude --debug

# Show only api and hooks categories
claude --debug "api,hooks"

# Exclude specific categories
claude --debug "!file,!1p"
```

Write debug logs to a specific file path instead of displaying them inline. Implicitly enables debug mode.

```bash  theme={null}
claude --debug-file /tmp/claude-debug.log
```

Minimal mode. Skips hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and `CLAUDE.md` auto-discovery. Sets `CLAUDE_CODE_SIMPLE=1`.

Authentication is limited to `ANTHROPIC_API_KEY` or `apiKeyHelper` via `--settings` (OAuth and keychain are not used).

Use `--bare` in scripted pipelines where startup latency matters and the features it disables are not needed. You can still provide context explicitly:

```bash  theme={null}
claude --bare \
  --system-prompt "$(cat context.md)" \
  --add-dir /project/libs \
  --mcp-config ./tools.json \
  -p "perform the analysis"
```

---

Flag combinations

Common flag patterns for scripting and automation:

# Non-interactive with JSON output
claude -p "list all exported types" --output-format json

# Bypass permissions in CI (sandboxed environment only)
claude -p "run full test suite and fix failures" --dangerously-skip-permissions

# Resume last session and continue non-interactively
claude --continue -p "now write the tests for that"

# Use a custom MCP config with strict isolation
claude --mcp-config ./ci-mcp.json --strict-mcp-config -p "analyze the schema"

# Append to system prompt without replacing it
claude --append-system-prompt "Always output TypeScript, not JavaScript."

Built with Mintlify.