Claude Code now has enough CLI surface area that a flat list of flags is not very useful anymore.

What matters is not memorizing every switch. What matters is knowing which arguments actually change how you work:

  • which ones make automation more reliable
  • which ones make sessions safer or more deterministic
  • which ones unlock custom agents and MCP workflows
  • which ones help you shape context instead of just throwing prompts at the tool

This post skips the “here is every option” approach and focuses on the flags that feel most consequential in real usage.

If you are mostly using Claude Code as a basic interactive terminal assistant, several of these will genuinely change what you think the CLI is for.

1. --add-dir: The Flag That Quietly Changes Scope

If you use Claude Code across multi-repo or split-directory setups, --add-dir is one of the most important arguments in the entire CLI.

What it does

It grants tool access to additional directories beyond the current working directory.

Why it matters

A lot of real work spans more than one folder:

  • app + backend
  • monorepo + design system package
  • primary repo + shared scripts
  • project directory + notes/docs/config repo

Without --add-dir, the model may be working with an artificially narrow view of your system.

Example

claude --add-dir ../api ../shared-ui

Best use case

Use it whenever the task crosses repository or folder boundaries and you want that extra context to be explicit instead of accidental.

2. --bare: The Best Way to Make Sessions Predictable

--bare is one of the strongest “serious workflow” flags in the CLI.

What it does

It starts Claude Code in minimal mode and skips a long list of automatic environment behaviors, including:

  • hooks
  • LSP
  • plugin sync
  • attribution
  • auto-memory
  • background prefetches
  • keychain reads
  • CLAUDE.md auto-discovery

Why it matters

This gives you a much cleaner, more deterministic starting point.

That is extremely useful for:

  • debugging weird environment behavior
  • benchmarking tasks
  • hermetic-ish automation
  • making a scripted run behave the same way every time

Why it is more important than it looks

A lot of advanced frustration with tools like Claude Code is not “the model was bad.” It is “the environment was different than I thought.”

--bare is one of the clearest ways to reduce that problem.

3. --agent and --agents: Where the CLI Starts Feeling Like a Platform

These flags are easy to underestimate.

What they do

  • --agent selects the current agent for the session.
  • --agents lets you define custom agents via JSON.

Why they matter

This turns the CLI from a single general-purpose tool into something more role-aware.

You can define temporary specialists for a session, such as:

  • reviewer
  • architect
  • test-writer
  • docs editor
  • bug triager

Example

claude --agents '{
  "reviewer": {
    "description": "Reviews risky changes",
    "prompt": "Focus on regressions, edge cases, and missing tests"
  }
}' --agent reviewer

Best use case

This is especially powerful for:

  • repeatable team workflows
  • temporary specialization
  • local experiments with agent roles
  • reducing prompt repetition for recurring tasks

This pair feels like one of the most future-facing parts of the CLI.

4. --mcp-config and --strict-mcp-config: The Deterministic MCP Combo

If you use MCP seriously, these are foundational.

What they do

  • --mcp-config loads MCP servers from JSON files or JSON strings.
  • --strict-mcp-config tells Claude Code to use only those MCP servers, ignoring all other MCP configurations.

Why they matter

MCP is powerful, but power without boundaries gets messy fast.

If you care about reproducibility, demos, or CI-like reliability, you do not want hidden local MCP configuration affecting the run.

Example

claude \
  --mcp-config ./mcp.json \
  --strict-mcp-config

Best use case

Use this pair when you need:

  • deterministic tool availability
  • a controlled integration surface
  • cleaner team handoff
  • safer automation environments

This is one of the clearest examples of the CLI maturing from “smart terminal helper” into “controllable engineering runtime.”

5. --print, --input-format, and --output-format: The Automation Core

These flags are where Claude Code stops looking like an interactive assistant and starts looking like infrastructure.

What they do

  • --print runs headlessly and exits
  • --input-format controls how input is supplied
  • --output-format controls how output is returned

Relevant formats include:

  • text
  • json
  • stream-json

Why they matter

If you want to wire Claude Code into scripts, wrappers, or internal tools, this is the center of gravity.

Examples

Simple print mode:

claude -p "summarize the risk in this diff"

Structured output:

claude -p --output-format json "extract the key action items"

Streaming orchestration:

claude -p \
  --input-format stream-json \
  --output-format stream-json

Best use case

Use these for:

  • shell scripts
  • CI helpers
  • editor integrations
  • dashboards
  • internal developer tooling

This trio is one of the biggest separators between casual CLI use and real systems use.

6. --json-schema: The Flag That Makes Output Less Wishful

If you automate Claude Code and still rely on “please return valid JSON,” you are living dangerously.

What it does

It validates structured output against a JSON schema.

Why it matters

This gives you stronger guarantees for downstream consumers:

  • scripts
  • APIs
  • dashboards
  • pipelines
  • bots

Example

claude -p \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "title": {"type": "string"},
      "risk": {"type": "string"}
    },
    "required": ["title", "risk"]
  }' \
  "Analyze this PR"

Best use case

This is one of the highest-value flags for anyone building reliable automation around the CLI.

7. --max-budget-usd: A Tiny Flag with Real Operational Value

This is not the most glamorous flag, but it is one of the most practical.

What it does

It sets a hard maximum dollar budget for API calls in print mode.

Why it matters

Once Claude Code starts moving into scripts and recurring workflows, cost control stops being optional.

Example

claude -p --max-budget-usd 2.00 "review this repository for dead code"

Best use case

Use it when:

  • experimenting with large prompts
  • running background jobs
  • giving teammates safer defaults
  • building internal tooling with bounded cost

This is the kind of flag that becomes more important the more successful your automation becomes.

8. --permission-mode, --allowedTools, --disallowedTools, and --tools

This is the cluster that defines how much power Claude actually has during a session.

Why this matters so much

A lot of Claude Code workflow design is really permission design.

You are not only deciding what task to run. You are deciding:

  • how interactive the session should be
  • what tools are available
  • what tools are silently allowed
  • what tools are completely off-limits

Useful pieces

  • --permission-mode: sets the overall permission strategy
  • --allowedTools: explicitly allow certain tools
  • --disallowedTools: explicitly deny certain tools
  • --tools: restrict the built-in tool set itself

Example

claude \
  --permission-mode plan \
  --tools "Read,Bash" \
  --disallowedTools "Edit"

Best use case

This cluster is excellent for:

  • safer audits
  • read-only investigations
  • demos
  • tightly controlled automation
  • giving a session exactly the amount of power it needs—and no more

9. --dangerously-skip-permissions and --allow-dangerously-skip-permissions

These flags deserve blunt language.

What they do

They allow bypassing normal permission checks.

Why they matter

Not because they are broadly useful, but because they are high consequence.

There are real situations where you want this:

  • isolated sandboxes
  • throwaway automation environments
  • trusted no-internet containers
  • very specific internal workflows

But outside those contexts, these flags can remove the safety rails that stop small mistakes from becoming expensive ones.

Best use case

Use them only where the environment itself is the safety boundary.

That is the right mental model.

10. --system-prompt and --append-system-prompt

These flags are more important than they seem because they let you control not just the task, but the operating frame around the task.

What they do

  • --system-prompt replaces the system prompt
  • --append-system-prompt adds guidance to the default system prompt

Why they matter

This is one of the cleanest ways to steer:

  • tone
  • risk posture
  • review criteria
  • team conventions
  • output discipline

Example

claude \
  --append-system-prompt "Be conservative. Prefer review comments over code edits." \
  "review this PR"

Best use case

Great for:

  • team norms
  • one-off strict review modes
  • output shaping in automation
  • temporary session-specific behavior without changing shared config

11. --resume, --continue, --fork-session, and --session-id

This group matters if you treat Claude Code conversations as real working sessions rather than disposable chats.

Why they matter

These flags help with continuity and branching:

  • --resume: jump back into a specific session
  • --continue: resume the most recent conversation in the current directory
  • --fork-session: resume while creating a new session ID instead of mutating the old one
  • --session-id: pin the conversation to a specific UUID

Best use case

This is especially useful when you want to:

  • preserve a “golden” investigative thread
  • branch from an earlier checkpoint
  • keep alternate approaches separate
  • build more deliberate long-running workflows

This cluster is underrated because it changes the ergonomics of multi-step work dramatically.

12. --worktree and --tmux: Serious Parallelism for Real Repos

These two flags are some of the most exciting for heavier engineering workflows.

What they do

  • --worktree creates a new git worktree for the session
  • --tmux creates a tmux session for that worktree

Why they matter

This is where Claude Code starts fitting into real parallel development patterns:

  • isolated experiments
  • branch-specific investigation
  • multiple tasks in motion at once
  • cleaner context separation

Example

claude --worktree feature-auth --tmux

Best use case

If you often split your attention across refactors, reviews, and investigations, this pair is much more meaningful than a generic “open a new terminal” workflow.

13. --plugin-dir and --settings

These are not the flashiest flags, but they are deeply useful for shaping one session without changing everything globally.

What they do

  • --plugin-dir loads plugins from a directory for that session only
  • --settings loads extra settings from a JSON file or JSON string

Why they matter

Session-local customization is a huge quality-of-life improvement.

You can experiment without contaminating your normal setup.

Best use case

Use them for:

  • experiments
  • demos
  • project-specific overrides
  • temporary local tooling

This is another sign that Claude Code is evolving toward a more composable runtime.

14. --include-partial-messages and --replay-user-messages

These are power-user flags, but they matter a lot if you care about observability and wrappers.

What they do

  • --include-partial-messages exposes partial chunks as they arrive
  • --replay-user-messages re-emits stdin user messages on stdout for acknowledgment in streaming JSON flows

Why they matter

These are not “better writing” flags. They are better integration flags.

They make it easier to build:

  • custom frontends
  • event-driven wrappers
  • streaming dashboards
  • multi-process orchestration

Best use case

If you are using Claude Code as a component inside a larger system, these become much more interesting than they look in the help text.

15. My Shortlist: The Flags Worth Learning First

If I had to give one focused shortlist from all of this, it would be:

  1. --add-dir
  2. --bare
  3. --agent / --agents
  4. --mcp-config + --strict-mcp-config
  5. --print + --output-format + --input-format
  6. --json-schema
  7. --max-budget-usd
  8. --permission-mode + tool restriction flags
  9. --fork-session
  10. --worktree + --tmux

That set covers the biggest jumps in:

  • determinism
  • orchestration
  • safety
  • cost control
  • multi-session workflow design

Final Thoughts

The most interesting Claude Code CLI flags are no longer just convenience options.

They define:

  • how much context Claude can access
  • how deterministic a run is
  • how much power the session has
  • whether the CLI behaves like a chat tool or an automation runtime
  • whether your workflow is disposable or structured

That is why the best flags are not just “nice to know.” They change the shape of the work.

If you only try a few after reading this, start with:

  • --add-dir
  • --bare
  • --strict-mcp-config
  • --json-schema
  • --permission-mode
  • --worktree

Those are the ones that most clearly push Claude Code from “helpful terminal assistant” toward “serious tool in the engineering stack.”