[Docs] 3 flags in --help not documented in CLI reference (v2.1.92): --brief, --file, --mcp-debug

CLI Reference Gap — 3 Flags in --help Not in Documentation (v2.1.92)

Ran a diff between claude --help (v2.1.92) and the CLI reference page. The docs now include a note that --help doesn't list every flag — but the reverse gap also exists.

Three flags appear in --help with no corresponding entry in the CLI reference:

| Flag | --help Description | Status |
|------|---------------------|--------|
| --brief | Enable SendUserMessage tool for agent-to-user communication | No docs entry |
| --file <specs...> | File resources to download at startup. Format: file_id:relative_path | No docs entry |
| --mcp-debug | [DEPRECATED. Use --debug instead] Enable MCP debug mode | No docs entry |

---

Detail

--brief

--brief    Enable SendUserMessage tool for agent-to-user communication

This appears to be related to headless/print-mode usage where Claude can prompt the user mid-run. No documentation found for the SendUserMessage tool or when this mode is appropriate.

--file <specs...>

--file <specs...>    File resources to download at startup. Format: file_id:relative_path
  (e.g., --file file_abc:doc.txt file_def:img.png)

The format suggests pre-loading file artifacts by ID (possibly from the Files API) into the session. No documentation found for the file ID format, where IDs come from, or what this is used for.

--mcp-debug (deprecated)

--mcp-debug    [DEPRECATED. Use --debug instead] Enable MCP debug mode (shows MCP server errors)

Deprecated flags are sometimes intentionally omitted from docs, but the deprecation note and migration path (--debug) would be useful to document for users who have --mcp-debug in scripts.

---

What Changed Since v2.1.86

The original gap was in the other direction: many flags existed in --help but weren't in the docs. Since then, the CLI reference has grown substantially and now documents flags that don't appear in --help at all (14 as of v2.1.92), with an explicit note: "claude --help does not list every flag, so a flag's absence from --help does not mean it is unavailable."

That note is a good fix. The remaining gap is the three flags above where --help is the only signal of existence.

---

Environment

• Claude Code v2.1.92 (Windows 11 Home, 10.0.26200)
• Docs checked: https://code.claude.com/docs/en/cli-reference (fetched 2026-04-07)