CLI Startup Flags Best Practice

Reference for Claude Code startup flags, top-level subcommands, and startup environment variables when launching Claude Code from the terminal.

Session Management
Model & Configuration
Permissions & Security
Output & Format
System Prompt
Agent & Subagent
MCP & Plugins
Directory & Workspace
Budget & Limits
Integration
Initialization & Maintenance
Debug & Diagnostics
Settings Override
Version & Help
Subcommands
Environment Variables

Session Management

Flag	Short	Description
`--continue`	`-c`	Continue the most recent conversation in the current directory
`--resume`	`-r`	Resume a specific session by ID or name, or show interactive picker
`--from-pr`		Resume sessions linked to a specific GitHub PR
`--fork-session`		Create a new session ID when resuming (use with `--resume` or `--continue`)
`--session-id`		Use a specific session ID (must be valid UUID)
`--no-session-persistence`		Disable session persistence (print mode only)
`--remote`		Create a new web session on claude.ai
`--teleport`		Resume a web session in your local terminal

Model & Configuration

Flag	Short	Description
`--model`		Set model with alias (`sonnet`, `opus`, `haiku`) or full model ID
`--fallback-model`		Auto-fallback model when default is overloaded (print mode only)
`--betas`		Beta headers to include in API requests (API key users only)

Permissions & Security

Flag	Short	Description
`--dangerously-skip-permissions`		Skip ALL permission prompts. Use with extreme caution
`--allow-dangerously-skip-permissions`		Enable permission bypassing as an option without activating it
`--permission-mode`		Begin in specified permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`
`--allowedTools`		Tools that execute without prompting (permission rule syntax)
`--disallowedTools`		Tools removed from model context entirely
`--tools`		Restrict which built-in tools Claude can use (use `""` to disable all)
`--permission-prompt-tool`		Specify MCP tool to handle permission prompts in non-interactive mode

Output & Format

Flag	Short	Description
`--print`	`-p`	Print response without interactive mode (headless/SDK mode)
`--output-format`		Output format: `text`, `json`, `stream-json`
`--input-format`		Input format: `text`, `stream-json`
`--json-schema`		Get validated JSON matching schema (print mode only)
`--include-partial-messages`		Include partial streaming events (requires `--print` and `--output-format=stream-json`)
`--verbose`		Enable verbose logging with full turn-by-turn output

System Prompt

Flag	Short	Description
`--system-prompt`		Replace entire system prompt with custom text
`--system-prompt-file`		Load system prompt from file, replacing default (print mode only)
`--append-system-prompt`		Append custom text to default system prompt
`--append-system-prompt-file`		Append file contents to default prompt (print mode only)

Agent & Subagent

Flag	Short	Description
`--agent`		Specify an agent for the current session
`--agents`		Define custom subagents dynamically via JSON
`--teammate-mode`		Set agent team display: `auto`, `in-process`, `tmux`

MCP & Plugins

Flag	Short	Description
`--mcp-config`		Load MCP servers from JSON file or string
`--strict-mcp-config`		Only use MCP servers from `--mcp-config`, ignore all others
`--plugin-dir`		Load plugins from directory for this session only (repeatable)

Directory & Workspace

Flag	Short	Description
`--add-dir`		Add additional working directories for Claude to access
`--worktree`	`-w`	Start Claude in an isolated git worktree (branched from HEAD)

Budget & Limits

Flag	Short	Description
`--max-budget-usd`		Maximum dollar amount for API calls before stopping (print mode only)
`--max-turns`		Limit number of agentic turns (print mode only)

Integration

Flag	Short	Description
`--chrome`		Enable Chrome browser integration for web automation
`--no-chrome`		Disable Chrome browser integration for this session
`--ide`		Automatically connect to IDE on startup if exactly one valid IDE available

Initialization & Maintenance

Flag	Short	Description
`--init`		Run initialization hooks and start interactive mode
`--init-only`		Run initialization hooks and exit (no interactive session)
`--maintenance`		Run maintenance hooks and exit

Debug & Diagnostics

Flag	Short	Description
`--debug`		Enable debug mode with optional category filtering (e.g., `"api,hooks"`)

Settings Override

Flag	Short	Description
`--settings`		Path to settings JSON file or JSON string to load
`--setting-sources`		Comma-separated list of sources to load: `user`, `project`, `local`
`--disable-slash-commands`		Disable all skills and slash commands for this session

Version & Help

Flag	Short	Description
`--version`	`-v`	Output the version number
`--help`	`-h`	Show help information

Subcommands

These are top-level commands run as claude :

Subcommand	Description
`claude`	Start interactive REPL
`claude "query"`	Start REPL with initial prompt
`claude agents`	List configured agents
`claude auth`	Manage Claude Code authentication
`claude doctor`	Run diagnostics from the command line
`claude install`	Install or switch Claude Code native builds
`claude mcp`	Configure MCP servers (`add`, `remove`, `list`, `get`, `enable`)
`claude plugin`	Manage Claude Code plugins
`claude remote-control`	Manage remote control sessions
`claude setup-token`	Create a long-lived token for subscription usage
`claude update` / `claude upgrade`	Update to the latest version

Environment Variables

These startup-only environment variables are set in your shell before launching Claude Code (they cannot be configured via settings.json):

Variable	Description
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`	Enable experimental agent teams. Also env-configurable — see Settings Reference
`CLAUDE_CODE_TMPDIR`	Override temp directory for internal files. Also configurable via `env` key — see Settings Reference
`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`	Enable additional directory CLAUDE.md loading. Also configurable via `env` key — see Settings Reference
`DISABLE_AUTOUPDATER=1`	Disable auto-updates. Also configurable via `env` key — see Settings Reference
`CLAUDE_CODE_EFFORT_LEVEL`	Control thinking depth — see Settings Reference
`USE_BUILTIN_RIPGREP=0`	Use system ripgrep instead of built-in (Alpine Linux)
`CLAUDE_CODE_SIMPLE`	Enable simple mode (Bash + Edit tools only). Also configurable via `env` key — see Settings Reference
`CLAUDE_BASH_NO_LOGIN=1`	Skip login shell for BashTool
`CCR_FORCE_BUNDLE=1`	Force bundling/uploading local repository when using `claude --remote`. Also configurable via `env` key — see Settings Reference

For environment variables configurable via the "env" key in settings.json (including MAX_THINKING_TOKENS, CLAUDE_CODE_SHELL, CLAUDE_CODE_ENABLE_TASKS, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, and more), see the Claude Settings Reference.