Quick Reference¶
The flags in the block below were written against claude 2.1.185 (2026-06-21);
re-check any of them against your installed version.
# Non-interactive with safety limits
claude -p "prompt" --permission-mode auto --max-turns 20
# Fan-out across files
for f in $(cat files.txt); do
claude -p "process $f" --permission-mode auto --allowedTools "Read,Edit" &
done; wait
# Structured output
claude -p "prompt" --output-format json | jq '.result'
# Resume a session
claude --continue # most recent
claude --resume # pick from list
# Plan mode (explore without editing)
# Shift+Tab cycles permission modes in interactive, or --permission-mode plan
# Clear context
/clear
# Compact with instructions
/compact Preserve: task objective, modified files, open questions
# Set a goal (loop until verified)
/goal all tests pass and build succeeds
# Run a skill
/fix-issue 1234
/deploy staging
Flags that do not mean what the snippet suggests¶
Version-stamped against claude 2.1.261, 2026-09-05.
| Gotcha | Detail |
|---|---|
--max-turns |
Still accepted, but no longer listed in claude --help — and silently inert on --bg (measured on 2.1.261: -p --max-turns 1 errors, --bg --max-turns 1 runs to completion) |
--max-budget-usd |
Help reads "(only works with --print)" — accepted but silently inert on a --bg session. With --max-turns also inert, a --bg session has no in-band ceiling at all |
--permission-prompts |
Documented "with --print" only, so a --bg session cannot fail closed this way |
| Variadic flags before the prompt | --add-dir, --allowedTools, --betas, --disallowedTools, --file, --mcp-config and --tools all take <...> lists and will swallow the positional prompt. Put the prompt first, or the variadic flag last |
claude agents --json |
Interactive sessions carry no id. Filter with --cwd "$PWD" or select(.kind=="background") before reading .id |
claude --bg -p |
Rejected outright since v2.1.198 (exit 1). Before that it created an unattachable session |
Each of these is worked through in Background Agents; the
--print-scoped permission guarantee is in Headless Mode.