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

[github-actions[bot]]

📊 Summary

• Total flags in src/cli-options.ts implementation: ~82 (including short-form aliases and the 5 logs/predownload subcommands)
• Flags with full 2-of-2 detailed-doc coverage (usage.md + cli-reference.md): ~50
• Flags undocumented in all detailed docs: ~19 (see list below)
• Critical inconsistency: --enable-api-proxy deprecation is not reflected in any documentation file — this is the most impactful finding.

✅ Flags Status

Flag	usage.md	cli-reference.md	README.md	AGENTS.md/CLAUDE.md	Status
-d, --allow-domains	✅	✅	✅	✅	✅ OK
--allow-domains-file	✅	✅	❌	❌	✅ OK (advanced flag)
--allow-urls	✅	✅	✅	❌	✅ OK
--allow-host-ports / --allow-host-service-ports	✅	✅	❌	❌	✅ OK
--block-domains / --block-domains-file	✅	✅	❌	❌	✅ OK
--dns-servers	✅	✅	❌	✅	✅ OK
--dns-over-https	✅	✅	❌	❌	✅ OK
--enable-api-proxy	⚠️ (opt-in)	⚠️ (opt-in)	❌	⚠️ ("optional")	⚠️ Outdated — deprecated in code
--no-enable-api-proxy	❌	❌	❌	❌	⚠️ Undocumented hard-error behavior
--enable-token-steering	❌	✅	❌	❌	⚠️ Missing from usage.md
--max-cache-misses	❌	❌	❌	❌	⚠️ Missing everywhere
--max-model-multiplier	❌	❌	❌	❌	⚠️ Missing everywhere
--max-model-multiplier-cap	❌	❌	❌	❌	⚠️ Missing everywhere
--max-permission-denied	❌	❌	❌	❌	⚠️ Missing everywhere
--anthropic-auto-cache	✅	❌	❌	❌	⚠️ Missing from cli-reference.md
--anthropic-cache-tail-ttl	✅	❌	❌	❌	⚠️ Missing from cli-reference.md
--anthropic-api-auth-header / --openai-api-auth-header	❌	❌	❌	❌	⚠️ Missing everywhere
--vertex-api-target / --vertex-api-base-path	❌	❌	❌	❌	⚠️ Missing everywhere (Gemini/OpenAI/Anthropic equivalents ARE documented)
--container-runtime	❌	❌	❌	❌	⚠️ Missing everywhere
--no-network-isolation	❌	❌	❌	❌	⚠️ Missing everywhere (--network-isolation only in usage.md)
--cloud-hypervisor-* (11 flags: binary/kernel/rootfs/supervisor/vcpus/memory-mib/api-timeout-ms/preview + 5 -sha256 variants)	❌	❌	❌	✅ (arch overview only, in CLAUDE.md)	⚠️ Entire feature family undocumented in usage.md/cli-reference.md
--docker-host-path-prefix	✅	❌	❌	✅	⚠️ Missing from cli-reference.md
--network-isolation	✅	❌	❌	❌	⚠️ Missing from cli-reference.md
--pids-limit	✅	❌	❌	❌	⚠️ Missing from cli-reference.md
--topology-attach	✅	❌	❌	❌	⚠️ Missing from cli-reference.md
--reflect	❌	❌	✅	❌	⚠️ README-only, missing from detailed docs
logs, logs stats, logs summary, logs audit, predownload	✅	✅	partial	partial	✅ OK, generally consistent

(Most other flags — --agent-image, --agent-timeout, --audit-dir, --config, --copilot-api-target, --diagnostic-logs, --difc-proxy-*, --docker-host, --enable-dind, --enable-dlp, --enable-host-access, --env-*, --exclude-env, --gemini-api-*, --image-registry, --image-tag, --log-level, --memory-limit, --no-rate-limit, --openai-api-*, --proxy-logs-dir, --rate-limit-*, --ruleset-file, --session-state-dir, --skip-pull, --ssl-bump, --tty, --upstream-proxy, --work-dir, -b/--build-local, -e/--env, -k/--keep-containers, -v/--mount — are consistently documented in usage.md and cli-reference.md, which is expected as the two detailed reference sources; README.md/CLAUDE.md intentionally stay high-level.)

⚠️ Issues Found

1. 🔴 CRITICAL: --enable-api-proxy deprecation is not reflected in any documentation

• Location: src/commands/validators/security-mode.ts (lines ~19, 128–148) is the source of truth.
• Issue: The API proxy sidecar is now always enabled for credential isolation. Passing --enable-api-proxy triggers a deprecation warning (⚠️ --enable-api-proxy is deprecated and no longer needed. The API proxy is always enabled.). Passing --no-enable-api-proxy is now a hard error (process.exit(1), message: ❌ --no-enable-api-proxy is not allowed. The API proxy is always enabled for credential isolation.).
• Expected: Docs should state the API proxy is on by default, mark --enable-api-proxy as a deprecated no-op flag, and document that --no-enable-api-proxy will abort execution.
• Current:
  • docs/usage.md (~lines 96–120): describes --enable-api-proxy as opt-in (default: false) and marks ~6 dependent flags as "(requires --enable-api-proxy)".
  • docs-site/src/content/docs/reference/cli-reference.md (line ~59, and ~15 example commands throughout, e.g. line 726): lists it in the flag table as false default and shows sudo -E awf --enable-api-proxy ... in numerous examples as if required.
  • CLAUDE.md/AGENTS.md (architecture section, "API Proxy Sidecar (optional)"): states "Enabled via --enable-api-proxy; not started otherwise" — directly contradicts current always-on behavior.
  • README.md: silent on the flag, doesn't clarify always-on status either.
• Suggestion: Update usage.md, cli-reference.md, and CLAUDE.md/AGENTS.md to (a) state the API proxy is always enabled, (b) mark --enable-api-proxy as deprecated/no-op with a warning, (c) document --no-enable-api-proxy as removed/hard error, (d) remove "(requires --enable-api-proxy)" qualifiers from dependent flag descriptions, and (e) drop --enable-api-proxy from example commands in cli-reference.md.

2. Entire Cloud Hypervisor flag family undocumented

• Location: src/cli-options.ts lines 191–202 define 11 --cloud-hypervisor-* flags (binary, kernel, rootfs, supervisor, vcpus, memory-mib, api-timeout-ms, preview, plus 5 -sha256 digest variants).
• Issue: None of these appear in docs/usage.md or cli-reference.md. Only a high-level architectural mention exists in CLAUDE.md (linking to docs/cloud-hypervisor-foundation.md).
• Suggestion: Add a dedicated "Cloud Hypervisor (preview)" section to usage.md and cli-reference.md, or explicitly cross-reference docs/cloud-hypervisor-foundation.md from both.

3. Token-steering/budget flags undocumented or partially documented

• Location: src/cli-options.ts lines ~415–447.
• Issue: --enable-token-steering is in cli-reference.md but missing from usage.md. Its companion flags --max-cache-misses, --max-model-multiplier, --max-model-multiplier-cap, and --max-permission-denied are missing from all docs.
• Suggestion: Add these four flags to both usage.md and cli-reference.md alongside --enable-token-steering, and add --enable-token-steering itself to usage.md.

4. Vertex AI proxy flags undocumented

• Location: src/cli-options.ts (--vertex-api-target, --vertex-api-base-path).
• Issue: Gemini/OpenAI/Anthropic equivalents (--gemini-api-target, --openai-api-target, --anthropic-api-target, etc.) are documented in both usage.md and cli-reference.md, but the Vertex AI variants are absent from all docs.
• Suggestion: Add Vertex AI flags alongside the other provider-target flags for consistency.

5. Cross-doc drift between usage.md and cli-reference.md

• Issue: Several flags appear in one detailed doc but not the other: --anthropic-auto-cache, --anthropic-cache-tail-ttl, --docker-host-path-prefix, --network-isolation, --pids-limit, --topology-attach (all in usage.md, missing from cli-reference.md); --enable-token-steering (in cli-reference.md, missing from usage.md).
• Suggestion: Reconcile the two reference docs so each carries the complete flag set; consider generating one canonical flag table to avoid future drift.

6. --reflect documented only in README.md

• Issue: --reflect appears in README.md but not in the two detailed reference docs (usage.md, cli-reference.md), the reverse of the usual gap pattern.
• Suggestion: Add --reflect to usage.md and cli-reference.md with a description matching README's usage.

7. Minor undocumented flags

• --container-runtime, --no-network-isolation, --anthropic-api-auth-header, --openai-api-auth-header are absent from all docs.
• Suggestion: Low-priority addition to usage.md/cli-reference.md flag tables.

📋 Recommendations

1. High Priority: Fix the --enable-api-proxy documentation across docs/usage.md, cli-reference.md, and CLAUDE.md/AGENTS.md — this is actively misleading since it describes opt-in behavior that no longer exists and doesn't warn about the --no-enable-api-proxy hard error.
2. Medium Priority: Document the Cloud Hypervisor flag family (11 flags) and the token-steering budget flags (--max-cache-misses, --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied), and the Vertex AI target/base-path flags.
3. Medium Priority: Reconcile drift between usage.md and cli-reference.md so both carry the same flag set (6+ flags differ between them).
4. Low Priority: Add --reflect to the detailed reference docs; document --container-runtime, --no-network-isolation, and the *-api-auth-header flags.

📁 Files Analyzed

• src/cli.ts, src/cli-options.ts, src/option-parsers.ts, src/commands/subcommands.ts, src/commands/validators/security-mode.ts (implementation)
• 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 · 54.9 AIC · ⊞ 9.7K · ◷

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