[CLI Flag Review] Weekly Audit — 2026-08-09

[github-actions[bot]]

📊 Summary

• Total flags in implementation (src/cli.ts/src/cli-options.ts root program): 68 top-level flags, plus logs/logs stats/logs summary/logs audit/predownload subcommands with their own options.
• Documented in docs/usage.md: 53/68 (15 missing)
• Documented in docs-site/.../cli-reference.md: 49/68 (19 missing)
• README.md / AGENTS.md / CLAUDE.md: intentionally list only a curated subset (quick-start flags), so raw "missing" counts there are expected and not flagged as issues except where noted below.
• Genuine inconsistencies found: 6 (2 high, 3 medium, 1 low priority)

✅ Flags Status (key differences only — full flag list checked, showing only rows with gaps in the two full-reference docs)

Flag	cli.ts	usage.md	cli-reference.md	Status
--container-runtime	✅	❌	❌	⚠️ Missing from both full-reference docs
--no-network-isolation	✅	❌	❌	⚠️ Missing from both
--legacy-security	✅	❌	❌	⚠️ Missing from both
--security-mode (deprecated)	✅ (hidden)	❌	❌	i️ OK to omit (hidden/deprecated)
--no-enable-api-proxy (removed)	✅ (hidden)	❌	❌	i️ OK to omit (hidden/removed)
--openai-api-auth-header	✅	❌	❌	⚠️ Missing from both
--anthropic-api-auth-header	✅	❌	❌	⚠️ Missing from both
--vertex-api-target	✅	❌	❌	⚠️ Missing from both
--vertex-api-base-path	✅	❌	❌	⚠️ Missing from both
--max-model-multiplier	✅	❌	❌	⚠️ Missing from both
--max-model-multiplier-cap	✅	❌	❌	⚠️ Missing from both
--max-permission-denied	✅	❌	❌	⚠️ Missing from both
--max-cache-misses	✅	❌	❌	⚠️ Missing from both
--enable-token-steering	✅	❌	✅	⚠️ Missing from usage.md only
--network-isolation	✅	✅	❌	⚠️ Missing from cli-reference.md
--topology-attach	✅	✅	❌	⚠️ Missing from cli-reference.md
--docker-host-path-prefix	✅	✅	❌	⚠️ Missing from cli-reference.md
--anthropic-auto-cache	✅	✅	❌	⚠️ Missing from cli-reference.md
--anthropic-cache-tail-ttl	✅	✅	❌	⚠️ Missing from cli-reference.md
--reflect	✅	❌	❌	⚠️ Missing from both full-reference docs (present in README.md only)

All other flags (allow-domains, block-domains, ssl-bump, build-local, image-, env, mount, memory-limit, tty, dns-servers/dns-over-https, upstream-proxy, enable-host-access, allow-host--ports, enable-dind, enable-dlp, enable-api-proxy(deprecated), copilot/openai/anthropic/gemini api-target/base-path, rate-limit-, difc-proxy-*, log-level, keep-containers, agent-timeout, work-dir, proxy-logs-dir, audit-dir, session-state-dir, diagnostic-logs) are documented consistently in both usage.md and cli-reference.md.

⚠️ Issues Found

1. --container-runtime completely undocumented in reference docs (High)

   • Location: src/cli-options.ts:172-178 defines this flag (gvisor/sbx isolation runtimes) but it appears in neither docs/usage.md nor docs-site/.../cli-reference.md.
   • Expected: A documented flag with description and example, given it's a security-relevant isolation option.
   • Suggestion: Add an "Image Management" or new "Isolation" section entry in both docs mirroring the cli.ts description.

2. --legacy-security and --no-network-isolation undocumented (High)

   • Location: src/cli-options.ts:250-253, 281-287. These are core security-mode toggles (network-isolation is "enabled by default"), yet neither is mentioned in usage.md or cli-reference.md, even though --network-isolation itself is documented in usage.md.
   • Expected: Docs should explain the default-on network-isolation mode and how --legacy-security/--no-network-isolation opt out, since this affects the security posture readers rely on.
   • Suggestion: Add a short "Security Modes" subsection cross-referencing these three related flags together.

3. API proxy advanced flags undocumented (Medium)

   • Location: --openai-api-auth-header, --anthropic-api-auth-header, --vertex-api-target, --vertex-api-base-path, --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses (cli-options.ts:334-415) are all missing from both usage.md and cli-reference.md, despite sibling flags (e.g. --anthropic-auto-cache, --rate-limit-rpm) being documented in the same "API Proxy" section.
   • Suggestion: Extend the API Proxy documentation sections in both files to cover these flags, following the existing pattern for --openai-api-target/--rate-limit-rpm.

4. --enable-token-steering documented in cli-reference.md but missing from usage.md (Medium)

   • Location: cli-reference.md:71, 922 has full docs; usage.md has no mention.
   • Suggestion: Add a matching entry to usage.md's API Proxy options table/section.

5. --network-isolation, --topology-attach, --docker-host-path-prefix, --anthropic-auto-cache, --anthropic-cache-tail-ttl documented in usage.md but missing from cli-reference.md (Medium)

   • These are documented in one reference doc but not the other, creating an asymmetric reference experience for users who consult only one file.
   • Suggestion: Port the existing usage.md descriptions into cli-reference.md's corresponding sections (Network & Security / Image Management / API Proxy).

6. --reflect flag only in README.md, not in either full CLI reference (Low)

   • Location: src/cli-options.ts:475-479 defines --reflect (debug flag to query the API proxy /reflect endpoint). It's mentioned in README.md but absent from both usage.md and cli-reference.md.
   • Suggestion: Add a brief entry under "Logging & Debug" in both docs.

📋 Recommendations

1. High Priority: Document --container-runtime, --legacy-security, and --no-network-isolation — these affect the default security posture and isolation guarantees, and their absence could mislead users about available hardening options.
2. Medium Priority: Backfill the 8 undocumented API-proxy advanced flags (auth headers, Vertex target/base-path, model-multiplier/cache-miss/permission-denied limits) and reconcile the 6 flags that are documented in only one of usage.md/cli-reference.md.
3. Low Priority: Add --reflect to the two full reference docs for completeness with README.md.

Deprecated/removed flags (--security-mode, --no-enable-api-proxy, --enable-api-proxy) are correctly hidden or marked deprecated in the CLI help and appropriately omitted or flagged in docs — no action needed there.

README.md, AGENTS.md, and CLAUDE.md intentionally document only a curated subset of flags for quick-start purposes; their large "missing" counts reflect this scope, not genuine drift, and are not flagged as issues.

📁 Files Analyzed

• src/cli.ts / src/cli-options.ts (implementation, root program options)
• src/commands/subcommands.ts (logs, logs stats, logs summary, logs audit, predownload)
• docs/usage.md
• docs-site/src/content/docs/reference/cli-reference.md
• README.md
• AGENTS.md
• CLAUDE.md

Generated by CLI Flag Consistency Checker · auto · 42.7 AIC · ⊞ 9.4K · ◷

• expires on Aug 16, 2026, 11:15 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-16T11:15:53.280Z.

Closed by Workflow