ailiteracynepal 🇳🇵
Text size

Chapter 01 · Section II · 10 min read

1.2 CLI reference: flags and output formats

The flags you'll actually type — working directories, permission mode, output format, one-shot mode. Enough to build a mental model of the invocation surface without memorising the man page.

claude on its own opens an interactive session. Every other invocation is that plus flags. Here are the ones you will reach for regularly, grouped by what they let you do.

Working directory & scope

claude                       # interactive session in $PWD
claude -p "review src/"      # one-shot: run a single prompt and exit
claude -c                    # continue the previous session
claude -r <session-id>       # resume a specific session by id
claude --add-dir ../shared   # widen the workspace to include another dir
  • -p / --print runs headless: takes a prompt, prints the result, exits. Essential for scripting.
  • -c / --continue picks up where you left off — no need to re-establish context.
  • --add-dir adds one or more directories to the session’s workspace. Use it for monorepos where the task spans apps/web + packages/ui.

Permission mode

claude --permission-mode acceptEdits   # auto-approve edits, prompt for shell
claude --permission-mode plan          # produce a plan, do not execute
claude --permission-mode bypassPermissions   # scary; sandbox only

Modes trade convenience for oversight. Pair them with denylists (Section 1.5) rather than loosening globally.

Output formats

claude -p "summarise" --output-format text        # default
claude -p "summarise" --output-format json        # structured envelope
claude -p "summarise" --output-format stream-json # NDJSON, one event per line
  • text prints the model’s reply as plain text. Good for humans.
  • json prints a single JSON object per invocation: metadata, cost, exit reason, the reply. Good for scripts.
  • stream-json prints one JSON event per line as they happen — tool calls, partial replies, final result. Good for pipes.

Small but useful

claude --model claude-sonnet-4-6         # override default model for one run
claude --system-prompt "..."             # override system prompt
claude --dangerously-skip-permissions   # for a truly isolated container only

Check your understanding

Quick check

—

You want to write a shell script that runs a Claude Code prompt and parses the cost + exit reason out of the result. Which output format is right?