[CLI Flag Review] Weekly CLI Flag Consistency Report

[github-actions[bot]]

📊 Summary

• Total flags in src/cli-options.ts (top-level awf command): 84 (plus 5 subcommand-scoped logs/predownload options)
• Flags with full 4-doc coverage (usage.md + cli-reference.md + README.md + CLAUDE.md): 0 — no flag is documented in all four files consistently; README.md and CLAUDE.md intentionally cover only a curated subset.
• Flags entirely undocumented in docs-site/.../cli-reference.md's Options Summary table: 21+ (see table below)
• Critical semantic inconsistency found: 1 (--enable-api-proxy — see Issue Improve links in readme to AW project #1)
• Missing flags (main audience-facing usage.md): 0 for user-relevant flags; --vertex-api-target, --vertex-api-base-path, --openai-api-auth-header, --anthropic-api-auth-header, --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses, --reflect, --enable-token-steering header text, and all 19 --cloud-hypervisor-* flags are missing from usage.md.

✅ Flags Status (selected — full 84-flag matrix available on request)

Legend: ✅ documented, ❌ not found, ➖ intentionally out of scope (advanced/internal)

Flag	cli.ts (source)	usage.md	cli-reference.md	README.md	Status
--allow-domains	✅	✅	✅	✅	✅ OK
--enable-api-proxy	✅ (deprecated/no-op)	✅ (stale)	✅ (stale)	— (correctly omitted)	🔴 Contradicts source
--pids-limit	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--network-isolation	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--no-network-isolation	✅	❌	❌	❌	⚠️ Undocumented everywhere
--legacy-security	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--container-runtime	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--network-subnet	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--topology-attach	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--verify-sbx-egress	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--security-mode	✅ (deprecated, hidden)	❌	❌	❌	➖ Intentionally hidden (OK)
--no-enable-api-proxy	✅ (removed/errors)	❌	❌	❌	➖ Intentionally hidden (OK)
--cloud-hypervisor-* (19 flags)	✅	❌	❌	➖ (linked to separate doc)	⚠️ Only covered in docs/cloud-hypervisor-foundation.md, not in usage.md/cli-reference.md
--vertex-api-target / --vertex-api-base-path	✅	❌	❌	✅ (mentioned as feature)	⚠️ Missing detailed docs despite README claiming Vertex AI support
--openai-api-auth-header / --anthropic-api-auth-header	✅	❌	❌	❌	⚠️ Undocumented everywhere
--max-model-multiplier(-cap)	✅	❌	❌	❌	⚠️ Undocumented everywhere
--max-permission-denied	✅	❌	❌	❌	⚠️ Undocumented everywhere
--max-cache-misses	✅	❌	❌	❌	⚠️ Undocumented everywhere
--reflect	✅	❌	❌	✅	⚠️ Missing from usage.md and cli-reference.md
--enable-token-steering	✅	❌	✅	✅ (feature bullet)	⚠️ Missing from usage.md
--anthropic-auto-cache / --anthropic-cache-tail-ttl	✅	✅	❌	✅ (feature bullet)	⚠️ Missing from cli-reference.md

⚠️ Issues Found

1. --enable-api-proxy documentation contradicts actual (deprecated/no-op) behavior — High severity

• Location: docs/usage.md (Command-Line Options block, and "API Proxy Sidecar" section ~line 569), docs-site/src/content/docs/reference/cli-reference.md (Options Summary table line 59, and ### --enable-api-proxy section ~line 727), CLAUDE.md lines 23/26/168
• Issue: src/cli-options.ts (lines 359–370) marks --enable-api-proxy [DEPRECATED] The API proxy is always enabled. This flag is ignored. and --no-enable-api-proxy as [REMOVED] (passing it is now an error). Both options are hideHelp()'d. Yet usage.md and cli-reference.md still present --enable-api-proxy as a live, opt-in flag with default false, complete with "Requires: --enable-api-proxy" call-outs on ~6 other API-target flag sections, and runnable examples showing sudo -E awf --enable-api-proxy .... CLAUDE.md (an agent-instruction file) states the sidecar is "optional" and "Enabled via --enable-api-proxy; not started otherwise" — directly wrong per the module docstring in CLAUDE.md itself, which elsewhere correctly says "Squid, the primary agent, and the general API proxy are the baseline services."
• Expected: All docs should state the API proxy sidecar is always enabled (per README.md, which already got this right: "API proxy sidecar (always enabled)"), and that --enable-api-proxy/--no-enable-api-proxy are deprecated/removed no-ops, not prerequisites for the other --*-api-target, --rate-limit-*, --anthropic-auto-cache, etc. flags.
• Current: Multiple runnable examples across usage.md and cli-reference.md instruct users to pass --enable-api-proxy; CLAUDE.md calls the whole component "optional" and conditionally started.
• Suggestion: Update cli-reference.md's Options Summary row and its dedicated ### --enable-api-proxy / ### --no-enable-api-proxy sections to reflect deprecation, strip --enable-api-proxy from all example commands and the "Requires:" call-outs on downstream flags, and correct CLAUDE.md's "API Proxy Sidecar (optional)" language (both occurrences) to match the "always enabled" framing already used in the "Core and Optional Container Components" heading.

2. docs-site/.../cli-reference.md Options Summary table omits ~21 implemented flags — Medium severity

• Location: docs-site/src/content/docs/reference/cli-reference.md, "Options Summary" table (lines ~20–71)
• Issue: The table (and the file overall) has zero mentions of: --pids-limit, --network-isolation, --no-network-isolation, --network-subnet, --legacy-security, --container-runtime, --topology-attach, --verify-sbx-egress, all 19 --cloud-hypervisor-* flags, --vertex-api-target, --vertex-api-base-path, --openai-api-auth-header, --anthropic-api-auth-header, --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses, --anthropic-auto-cache, --anthropic-cache-tail-ttl, --reflect. Some of these (network-isolation, container-runtime, cloud-hypervisor preview) are core security/runtime features described at length in usage.md and CLAUDE.md, so their absence from the canonical CLI reference is a real gap, not an intentional omission of internal-only flags.
• Expected: cli-reference.md, being the most detailed reference doc, should have the widest flag coverage of all docs (a superset of usage.md).
• Current: cli-reference.md is missing flags that usage.md already documents (e.g., --network-isolation, --container-runtime, --pids-limit), reversing the expected coverage order.
• Suggestion: Add rows/sections for these flags, at minimum mirroring what's already written in usage.md, and add a dedicated "Cloud Hypervisor Preview" reference section (or a clear cross-link to docs/cloud-hypervisor-foundation.md).

3. usage.md missing ~13 API-proxy/vertex/reflect flags — Medium priority

• Location: docs/usage.md, "Command-Line Options" block (lines 3–187) and "API Proxy Sidecar" section (~line 569)
• Issue: --vertex-api-target, --vertex-api-base-path, --openai-api-auth-header, --anthropic-api-auth-header, --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses, --reflect, and --enable-token-steering are absent from the options block even though sibling flags (e.g. --rate-limit-rpm, --anthropic-auto-cache) are documented right next to them in cli-options.ts.
• Expected: Given usage.md's options block otherwise closely mirrors cli-options.ts grouping order, these flags should appear inline with their neighbors.
• Suggestion: Add entries for the missing flags in the same source-code order to keep the doc a reliable mirror of --help output.

4. docs/cloud-hypervisor-foundation.md is the sole home for 19 --cloud-hypervisor-* flags — Low/Medium priority

• Location: src/cli-options.ts lines 196–218 define --cloud-hypervisor-preview plus 18 related flags (binary paths, sha256 digests, vcpus, memory, timeouts, mount-policy, development-only unattested-artifacts escape hatch).
• Issue: None of these appear in usage.md or cli-reference.md's Options Summary; they're preview/experimental (GitHub-hosted Ubuntu x86_64 KVM only) so a separate deep-dive doc is reasonable, but neither of the two primary CLI docs even cross-links to docs/cloud-hypervisor-foundation.md from the Options table itself (README.md does link it under "Explore the docs").
• Suggestion: Add a one-line summary row/section in cli-reference.md pointing to the dedicated doc, consistent with how README.md already cross-links it.

📋 Recommendations

1. High Priority: Fix the --enable-api-proxy deprecation inconsistency (Issue Improve links in readme to AW project #1) — this is user-facing and could cause confusion/errors since users following cli-reference.md's examples would pass a no-op flag while believing it's required, and CLAUDE.md (read by coding agents working on this repo) actively misdescribes the architecture.
2. Medium Priority: Backfill cli-reference.md's Options Summary table with the ~21 missing flags (Issue Secret proxying #2), prioritizing --network-isolation/--container-runtime/--legacy-security since these are core security-mode flags, not obscure edge cases.
3. Medium Priority: Backfill usage.md with the ~10 missing flags (Issue feat: add integration test for rostbuness #3), especially --reflect (already advertised in README.md's Quick Start) and the --max-* budget-guard flags (cost-control features users would want to discover).
4. Low Priority: Add a cross-reference row/section in cli-reference.md for Cloud Hypervisor flags pointing at the dedicated doc (Issue fix: add missing Docker image pulls to robustness test workflow #4).

📁 Files Analyzed

• src/cli.ts (thin entry point — delegates to src/cli-options.ts + src/commands/subcommands.ts)
• src/cli-options.ts (source of truth — 84 top-level flags)
• src/commands/subcommands.ts (source of truth — predownload, logs, logs stats, logs summary, logs audit subcommand flags; all subcommand options were found consistently documented in usage.md's Commands block)
• docs/usage.md
• docs-site/src/content/docs/reference/cli-reference.md
• README.md
• AGENTS.md (symlink to CLAUDE.md — identical content, reviewed once)
• CLAUDE.md

Generated by CLI Flag Consistency Checker · copilot · auto · 81.7 AIC · ⊞ 9.7K · ◷

• expires on Sep 28, 2026, 6:00 PM UTC

[github-actions[bot]]

🔮 The ancient spirits stir. The smoke test agent was here, and the omens read clear.

Warning

Firewall blocked 8 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• contentautofill.googleapis.com
• msfeed25.pkgs.visualstudio.com
• update.googleapis.com
• www.google.com
• www.gstatic.com

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

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "contentautofill.googleapis.com"
    - "msfeed25.pkgs.visualstudio.com"
    - "update.googleapis.com"
    - "www.google.com"
    - "www.gstatic.com"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex
_{Add label ready-for-aw to run again}