[DOCS] CLI Reference lacks guidance on environment-variable-only configuration options

Documentation Type

Other

Documentation Location

• https://code.claude.com/en/cli-reference

Section/Topic

CLI flags table and general guidance on advanced configuration

Current Documentation

The CLI Reference documents all available command-line flags (e.g., --model, --max-turns, --max-budget-usd) but does not mention that some configuration options are only available via environment variables or settings.json.

For example, users looking for a way to control auto-compaction thresholds would search the CLI Reference and find nothing. The CLAUDE_AUTOCOMPACT_PCT_OVERRIDE environment variable is documented in the Settings page but not cross-referenced.

What's Wrong or Missing?

Discoverability gap: Users consulting the CLI Reference to configure Claude Code's behavior may not realize that additional configuration options exist only as environment variables.

The Settings page (settings.md) documents 70+ environment variables including:

• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE - controls when auto-compaction triggers
• MAX_THINKING_TOKENS - controls extended thinking budget
• BASH_DEFAULT_TIMEOUT_MS - controls default bash timeout
• MAX_MCP_OUTPUT_TOKENS - controls MCP response limits

None of these have corresponding CLI flags, and the CLI Reference doesn't indicate this architecture.

Note on original trigger: The original issue claimed the changelog references this feature. I verified this is incorrect—the changelog contains no mention of CLAUDE_AUTOCOMPACT_PCT_OVERRIDE or compaction percentage configuration.

Suggested Improvement

Add a brief section to the CLI Reference page after the flags table:

## Advanced configuration

Some configuration options are available only through environment variables or `settings.json`, not as CLI flags. These include:

- Auto-compaction thresholds (`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`)
- Extended thinking token budget (`MAX_THINKING_TOKENS`)
- Bash command timeouts (`BASH_DEFAULT_TIMEOUT_MS`, `BASH_MAX_TIMEOUT_MS`)
- Output token limits (`CLAUDE_CODE_MAX_OUTPUT_TOKENS`, `MAX_MCP_OUTPUT_TOKENS`)

For the complete list of environment variables, see [Settings > Environment Variables](https://code.claude.com/en/settings#environment-variables).

Alternatively, add a one-line note at the end of the CLI flags section:

Note: For advanced configuration options not available as CLI flags (such as compaction thresholds, token limits, and timeouts), see Environment Variables.

Impact

Low - This is a usability improvement, not a correctness issue. The documentation is accurate; it's just a matter of helping users discover configuration options that aren't CLI flags.

Impact

High - Prevents users from using a feature

Additional Context

Files in documentation mirror

| File | Issue |
|------|-------|
| code-claude/docs/en/cli-reference.md | No mention of env-var-only configuration |

Related documentation (correctly documents the env var)

| File | Line | Content |
|------|------|---------|
| code-claude/docs/en/settings.md | 782 | Full documentation of CLAUDE_AUTOCOMPACT_PCT_OVERRIDE |
| code-claude/docs/en/sub-agents.md | 522 | Cross-references the env var for subagent compaction |

Verification steps performed

1. ✅ Confirmed CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is documented in settings.md
2. ✅ Confirmed no CLI flag exists for compaction percentage in cli-reference.md
3. ❌ Confirmed changelog does NOT reference this feature (original claim was incorrect)
4. ✅ Confirmed sub-agents.md correctly references the environment variable