[CLI Flag Review] CLI Flag Consistency Report — Weekly Review

[github-actions[bot]]

Weekly automated consistency check between src/cli-options.ts and documentation.
Generated: 2026-06-15

---

📊 Summary

Metric	Count
Total flags in src/cli-options.ts	61
Flags documented in docs/usage.md	55
Flags documented in docs-site/.../cli-reference.md	53
Inconsistencies found	11

---

✅ Flags Status

Flags with complete, consistent documentation are omitted for brevity. The table below shows flags with issues only.

Flag	cli.ts	usage.md	cli-reference.md	README	AGENTS.md	Status
--openai-api-auth-header	✅	❌	❌	❌	❌	🔴 Missing docs
--anthropic-api-auth-header	✅	❌	❌	❌	❌	🔴 Missing docs
--max-model-multiplier	✅	❌	❌	❌	❌	🔴 Missing docs
--max-model-multiplier-cap	✅	❌	❌	❌	❌	🔴 Missing docs
--max-permission-denied	✅	❌	❌	❌	❌	🔴 Missing docs
--docker-host-path-prefix	✅	✅	❌	❌	✅	🟡 Missing from cli-reference
--anthropic-auto-cache	✅	✅	❌	❌	❌	🟡 Missing from cli-reference
--anthropic-cache-tail-ttl	✅	✅	❌	❌	❌	🟡 Missing from cli-reference
--enable-token-steering	✅	❌	✅	❌	❌	🟡 Missing from usage.md
--dns-servers default	✅	✅	✅	❌	⚠️	🟢 Minor value discrepancy
--enable-api-proxy description	✅	✅	✅	✅	✅	🟢 Minor description gap

---

⚠️ Issues Found

Issue 1 — --openai-api-auth-header undocumented

• Location: src/cli-options.ts line 290
• Issue: Flag exists in implementation but appears in no documentation file
• Expected: Entry in docs/usage.md (options block) and docs-site/.../cli-reference.md (summary table + details section)
• Current: No documentation anywhere
• Suggestion: Add to both docs. Description: "Custom auth header name for OpenAI requests (default: Authorization with Bearer prefix)"

Issue 2 — --anthropic-api-auth-header undocumented

• Location: src/cli-options.ts line 295
• Issue: Flag exists in implementation but appears in no documentation file
• Expected: Entry in docs/usage.md and docs-site/.../cli-reference.md
• Current: No documentation anywhere
• Suggestion: Add to both docs. Description: "Custom auth header name for Anthropic requests (default: x-api-key)"

Issue 3 — --max-model-multiplier undocumented

• Location: src/cli-options.ts line 334
• Issue: Flag exists in implementation but appears in no documentation file
• Expected: Entry in docs/usage.md and docs-site/.../cli-reference.md
• Current: No documentation anywhere
• Suggestion: Add to the API Proxy section of both docs. Per-model cost multipliers for effective token accounting; format: model:multiplier,... pairs

Issue 4 — --max-model-multiplier-cap undocumented

• Location: src/cli-options.ts line 342
• Issue: Flag exists in implementation but appears in no documentation file
• Expected: Entry in docs/usage.md and docs-site/.../cli-reference.md
• Current: No documentation anywhere
• Suggestion: Add alongside --max-model-multiplier. Description: "Maximum allowed model cost multiplier; requests exceeding the cap are rejected with HTTP 400"

Issue 5 — --max-permission-denied undocumented

• Location: src/cli-options.ts line 349
• Issue: Flag exists in implementation but appears in no documentation file
• Expected: Entry in docs/usage.md and docs-site/.../cli-reference.md
• Current: No documentation anywhere
• Suggestion: Add to API Proxy section. Description: "Max upstream 401/403 responses per run; when reached, subsequent requests are rejected with HTTP 403 to stop token waste on misconfigured credentials"

Issue 6 — --docker-host-path-prefix missing from cli-reference.md

• Location: docs-site/src/content/docs/reference/cli-reference.md
• Issue: Flag is documented in docs/usage.md (lines 123–126) and AGENTS.md but absent from the CLI reference summary table
• Expected: Row in the Options Summary table and a dedicated details section
• Current: Not present in cli-reference.md
• Suggestion: Add table row and ### --docker-host-path-prefix details section; cross-link to ARC/DinD docs

Issue 7 — --anthropic-auto-cache missing from cli-reference.md

• Location: docs-site/src/content/docs/reference/cli-reference.md
• Issue: Flag is in docs/usage.md (lines 100–103) but absent from the CLI reference
• Expected: Row in Options Summary table and details section
• Current: Not present in cli-reference.md
• Suggestion: Add table row: | --anthropic-auto-cache | flag | false | Enable Anthropic prompt-cache optimizations (requires --enable-api-proxy) |

Issue 8 — --anthropic-cache-tail-ttl missing from cli-reference.md

• Location: docs-site/src/content/docs/reference/cli-reference.md
• Issue: Flag is in docs/usage.md (lines 104–107) but absent from the CLI reference
• Expected: Row in Options Summary table alongside --anthropic-auto-cache
• Current: Not present in cli-reference.md
• Suggestion: Add table row: | --anthropic-cache-tail-ttl <5m\|1h> | string | 5m | TTL for rolling-tail cache breakpoint (requires --anthropic-auto-cache) |

Issue 9 — --enable-token-steering missing from docs/usage.md

• Location: docs/usage.md
• Issue: Flag is documented in cli-reference.md (lines 71, 922–931) but absent from the options block in docs/usage.md
• Expected: Entry in the options block (lines 108–132 range)
• Current: Not present in docs/usage.md
• Suggestion: Add after --no-rate-limit entry: --enable-token-steering Inject budget-warning messages at 80/90/95/99% effective token usage (requires --enable-api-proxy). (default: false)

Issue 10 — --dns-servers default value in AGENTS.md

• Location: AGENTS.md — DNS Configuration section (line ~194)
• Issue: AGENTS.md states Default: Google DNS (8.8.8.8,8.8.4.4) but actual behavior is auto-detection from host resolvers with a fallback
• Expected: "Auto-detected from host resolvers; falls back to 8.8.8.8,8.8.4.4"
• Current: "Default: Google DNS (8.8.8.8,8.8.4.4)"
• Suggestion: Update to: "Default: auto-detected from host resolvers (falls back to 8.8.8.8,8.8.4.4)"

Issue 11 — --enable-api-proxy description omits Copilot and Gemini

• Location: src/cli-options.ts line 265
• Issue: CLI --help output says "Supports OpenAI (Codex) and Anthropic (Claude) APIs" — omits GitHub Copilot and Gemini, which are also supported
• Expected: "Supports OpenAI, Anthropic, GitHub Copilot, and Gemini APIs"
• Current: "Supports OpenAI (Codex) and Anthropic (Claude) APIs"
• Suggestion: Update the .option() description in cli-options.ts to mention all four providers

---

📋 Recommendations

🔴 High Priority (flags with zero documentation)

1. Add --openai-api-auth-header to docs/usage.md and cli-reference.md
2. Add --anthropic-api-auth-header to docs/usage.md and cli-reference.md
3. Add --max-model-multiplier to docs/usage.md and cli-reference.md
4. Add --max-model-multiplier-cap to docs/usage.md and cli-reference.md
5. Add --max-permission-denied to docs/usage.md and cli-reference.md

🟡 Medium Priority (cross-doc inconsistencies)

6. Add --docker-host-path-prefix to docs-site/.../cli-reference.md summary table + details section
7. Add --anthropic-auto-cache to docs-site/.../cli-reference.md
8. Add --anthropic-cache-tail-ttl to docs-site/.../cli-reference.md
9. Add --enable-token-steering to docs/usage.md options block

🟢 Low Priority (minor inaccuracies)

10. Correct --dns-servers default description in AGENTS.md
11. Update --enable-api-proxy description in cli-options.ts to list all four supported providers (OpenAI, Anthropic, Copilot, Gemini)

---

📁 Files Analyzed

• src/cli-options.ts — implementation source of truth (61 flags)
• docs/usage.md — user-facing usage guide (1207 lines)
• docs-site/src/content/docs/reference/cli-reference.md — CLI reference docs (1391 lines)
• README.md — project overview (104 lines)
• AGENTS.md / CLAUDE.md — agent instruction files

Generated by CLI Flag Consistency Checker · ◷

• expires on Jun 22, 2026, 7:19 PM UTC

[github-actions[bot]]

🔮 The ancient spirits stir, and the smoke test agent was here. The omens are favorable; the discussion echo is complete.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-22T19:19:48.084Z.

Closed by Workflow