cli-reference ยท diff

git:20260808.3b763b1 to git:20261104.1844d11

17 added, 227 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

- ---
- name: cli-reference
- description: Claude Code CLI commands, flags, headless mode, and automation patterns
- allowed-tools: [Read]
- ---
-
- # CLI Reference
-
- Complete reference for Claude Code command-line interface.
-
- ## When to Use
-
- - "What CLI flags are available?"
- - "How do I use headless mode?"
- - "Claude in automation/CI/CD"
- - "Output format options"
- - "System prompt via CLI"
- - "How do I spawn agents properly?"
-
- ## Core Commands
-
- | Command | Description | Example |
- |---------|-------------|---------|
- | `claude` | Start interactive REPL | `claude` |
- | `claude "query"` | REPL with initial prompt | `claude "explain this project"` |
- | `claude -p "query"` | Headless mode (SDK) | `claude -p "explain function"` |
- | `cat file \| claude -p` | Process piped content | `cat logs.txt \| claude -p "explain"` |
- | `claude -c` | Continue most recent | `claude -c` |
- | `claude -c -p "query"` | Continue via SDK | `claude -c -p "check types"` |
- | `claude -r "id" "query"` | Resume session | `claude -r "auth" "finish PR"` |
- | `claude update` | Update version | `claude update` |
- | `claude mcp` | Configure MCP servers | See MCP docs |
-
- ## Session Control
-
- | Flag | Description | Example |
- |------|-------------|---------|
- | `--continue, -c` | Load most recent conversation | `claude --continue` |
- | `--resume, -r` | Resume session by ID/name | `claude --resume auth-refactor` |
- | `--session-id` | Use specific UUID | `claude --session-id "550e8400-..."` |
- | `--fork-session` | Create new session on resume | `claude --resume abc --fork-session` |
-
- ## Headless Mode (Critical for Agents)
-
- | Flag | Description | Example |
- |------|-------------|---------|
- | `--print, -p` | Non-interactive, exit after | `claude -p "query"` |
- | `--output-format` | `text`, `json`, `stream-json` | `claude -p --output-format json` |
- | `--max-turns` | Limit agentic turns | `claude -p --max-turns 100 "query"` |
- | `--verbose` | Full turn-by-turn output | `claude --verbose` |
- | `--dangerously-skip-permissions` | Skip permission prompts | `claude -p --dangerously-skip-permissions` |
- | `--include-partial-messages` | Include streaming events | `claude -p --output-format stream-json --include-partial-messages` |
- | `--input-format` | Input format (text/stream-json) | `claude -p --input-format stream-json` |
-
- ## Tool Control
-
- | Flag | Description | Example |
- |------|-------------|---------|
- | `--allowedTools` | Auto-approve these tools | `"Bash(git log:*)" "Read"` |
- | `--disallowedTools` | Block these tools | `"Bash(rm:*)" "Edit"` |
- | `--tools` | Only allow these tools | `--tools "Bash,Edit,Read"` |
-
- ## Subagent Definition (--agents flag)
-
- Define custom subagents inline via JSON:
-
- ```bash
- claude --agents '{
- "code-reviewer": {
- "description": "Expert code reviewer. Use proactively after code changes.",
- "prompt": "You are a senior code reviewer. Focus on code quality and security.",
- "tools": ["Read", "Grep", "Glob", "Bash"],
- "model": "inherit"
- },
- "debugger": {
- "description": "Debugging specialist for errors and test failures.",
- "prompt": "You are an expert debugger. Analyze errors and provide fixes."
- }
- }'
- ```
-
- ### Agent Fields
-
- | Field | Required | Description |
- |-------|----------|-------------|
- | `description` | Yes | When to invoke this agent |
- | `prompt` | Yes | System prompt for behavior |
- | `tools` | No | Allowed tools (inherits all if omitted) |
- | `model` | No | Claude adapter only; omit it or use `inherit` so the parent model remains authoritative |
-
- ### Key Insight
- When Lead uses Task tool, it auto-spawns from these definitions. No manual spawn needed.
-
- ## System Prompt Customization
-
- | Flag | Behavior | Modes |
- |------|----------|-------|
- | `--system-prompt` | **Replace** entire prompt | Interactive + Print |
- | `--system-prompt-file` | **Replace** from file | Print only |
- | `--append-system-prompt` | **Append** to default (recommended) | Interactive + Print |
-
- **Use `--append-system-prompt`** for most cases - preserves Claude Code capabilities.
-
- ## Model Selection (Claude adapter only)
-
- | Flag | Description | Example |
- |------|-------------|---------|
- | `--model` | Set model for session | `--model claude-sonnet-4-5` |
- | `--fallback-model` | Fallback if default overloaded | `--fallback-model sonnet` |
-
- Aliases: `sonnet`, `opus`, `haiku`. Codex and `luna_worker` do not read this router guidance.
-
- ## MCP Configuration
-
- | Flag | Description | Example |
- |------|-------------|---------|
- | `--mcp-config` | Load MCP servers from JSON | `--mcp-config ./mcp.json` |
- | `--strict-mcp-config` | Only use these MCP servers | `--strict-mcp-config --mcp-config ./mcp.json` |
-
- ## Advanced Flags
-
- | Flag | Description | Example |
- |------|-------------|---------|
- | `--add-dir` | Add working directories | `--add-dir ../apps ../lib` |
- | `--agent` | Specify agent for session | `--agent my-custom-agent` |
- | `--permission-mode` | Start in permission mode | `--permission-mode plan` |
- | `--permission-prompt-tool` | MCP tool for permissions | `--permission-prompt-tool mcp_auth` |
- | `--plugin-dir` | Load plugins from directory | `--plugin-dir ./my-plugins` |
- | `--settings` | Load settings from file/JSON | `--settings ./settings.json` |
- | `--setting-sources` | Which settings to load | `--setting-sources user,project` |
- | `--betas` | Beta API headers | `--betas interleaved-thinking` |
- | `--debug` | Enable debug mode | `--debug "api,hooks"` |
- | `--ide` | Auto-connect to IDE | `--ide` |
- | `--chrome` | Enable Chrome integration | `--chrome` |
- | `--no-chrome` | Disable Chrome for session | `--no-chrome` |
- | `--enable-lsp-logging` | Verbose LSP debugging | `--enable-lsp-logging` |
- | `--version, -v` | Output version | `claude -v` |
-
- ## Output Formats
-
- ### JSON (for parsing)
- ```bash
- claude -p "query" --output-format json
- # {"result": "...", "session_id": "...", "usage": {...}}
- ```
-
- ### Streaming (for real-time monitoring)
- ```bash
- claude -p "query" --output-format stream-json
- # Newline-delimited JSON events
- ```
-
- ### Structured Output (schema validation)
- ```bash
- claude -p "Extract data" \
- --output-format json \
- --json-schema '{"type":"object","properties":{...}}'
- ```
-
- ## Headless Agent Pattern (CRITICAL)
-
- Proper headless agent spawn:
-
- ```bash
- claude -p "$TASK_PROMPT" \
- --session-id "$UUID" \
- --dangerously-skip-permissions \
- --max-turns 100 \
- --output-format stream-json \
- --agents '{...}' \
- --append-system-prompt "Context: ..."
- ```
-
- **Missing any of these causes hangs:**
- - `--session-id` - Track the session
- - `--dangerously-skip-permissions` - Headless requires this
- - `--max-turns` - Prevents infinite loops
-
- ## Common Patterns
-
- ### CI/CD Automation
- ```bash
- claude -p "Run tests and fix failures" \
- --dangerously-skip-permissions \
- --max-turns 50 \
- --output-format json | jq '.result'
- ```
-
- ### Piped Input
- ```bash
- cat error.log | claude -p "Find root cause"
- gh pr diff | claude -p "Review for security"
- ```
-
- ### Multi-turn Session
- ```bash
- id=$(claude -p "Start task" --output-format json | jq -r '.session_id')
- claude -p "Continue" --resume "$id"
- ```
-
- ### Stream Monitoring
- ```bash
- claude -p "Long task" \
- --output-format stream-json \
- --include-partial-messages | while read -r line; do
- echo "$line" | jq '.type'
- done
- ```
-
- ## Keyboard Shortcuts (Interactive)
-
- | Shortcut | Action |
- |----------|--------|
- | `Ctrl+C` | Cancel current |
- | `Ctrl+D` | Exit |
- | `Ctrl+R` | Reverse search history |
- | `Esc Esc` | Rewind changes |
- | `Shift+Tab` | Toggle permission mode |
-
- ## Quick Commands
-
- | Prefix | Action |
- |--------|--------|
- | `/` | Slash command |
- | `!` | Bash mode |
- | `#` | Add to memory |
- | `@` | File mention |
+ ---
+ name: cli-reference
+ description: Find version-correct Claude Code CLI flags and configure bounded headless or interactive commands.
+ allowed-tools: [Read, Bash]
+ ---
+
+ # CLI Reference
+
+ If `claude` is available, check `claude --version` and `claude --help` for exact options. Otherwise use current official documentation and report host validation unavailable; do not install the CLI just to answer. Do not assume a remembered flag exists. Codex is a separate host with its own commands and worker configuration.
+
+ Common patterns are interactive `claude`, a supplied initial prompt, and print/headless mode `claude -p <prompt>`. Verify resume, output format, tool permissions and turn limits against the installed version before using them. Capture command arguments as structured data; avoid shell interpolation of prompts or filenames.
+
+ For automation, set a task-specific working directory, bounded scope and an appropriate execution limit. Supply only needed context and tools. Preserve normal permission handling; an unattended workflow does not imply permission to bypass it. Do not start recursive agents or external side effects merely to demonstrate flags.
+
+ For a local vibecosystem checkout, inspect installation with `node bin/cli.mjs init --profile core --dry-run`. Use `npx vibecosystem init` only when the published package is intended. `vibeco help` describes the installed CLI; `effective-config`, `stats` and `doctor` inspect runtime state. Profile changes need a retained source checkout and preserve conflicting user files.
+
+ Explain the selected command, relevant options and observed result without dumping a complete external manual.