[CLI Flag Review] AWF CLI Flag Consistency Report — 2026-07-20

[github-actions[bot]]

📊 Summary

Weekly automated analysis of CLI flag consistency between implementation and documentation.

Analysis date: 2026-07-20

Metric	Count
Total flags in src/cli-options.ts	71 (68 visible, 3 deprecated/hidden)
Flags documented in docs/usage.md	~55
Flags documented in docs-site/.../cli-reference.md	~52
Flags documented in README.md	~10 (abbreviated)
Issues found	12

---

✅ Flags Status

Flags present in implementation but missing from cli-reference.md

Flag	cli-options.ts	usage.md	cli-reference.md	Notes
--network-isolation / --no-network-isolation	✅	✅	❌	Not in reference options table or section
--topology-attach	✅	✅	❌	Not in reference options table
--docker-host-path-prefix	✅	✅	❌	Not in reference options table
--container-runtime	✅	❌	❌	Missing from both docs
--vertex-api-target	✅	❌	❌	Missing from both docs
--vertex-api-base-path	✅	❌	❌	Missing from both docs
--openai-api-auth-header	✅	❌	❌	Missing from both docs
--anthropic-api-auth-header	✅	❌	❌	Missing from both docs
--max-model-multiplier	✅	❌	❌	Missing from both docs
--max-model-multiplier-cap	✅	❌	❌	Missing from both docs
--max-permission-denied	✅	❌	❌	Missing from both docs
--max-cache-misses	✅	❌	❌	Missing from both docs

Deprecated/hidden flags with outdated documentation

Flag	Status in code	Status in docs
--enable-api-proxy	hideHelp(), marked [DEPRECATED] — API proxy always enabled	Both usage.md and cli-reference.md still document it as a working opt-in feature with many examples
--security-mode	hideHelp(), marked [DEPRECATED] — use --legacy-security	Not explicitly called out as deprecated in either doc

Flags with description discrepancies

Flag	cli-options.ts description	usage.md / cli-reference.md
--network-isolation	"Enabled by default (strict security)."	usage.md says "Experimental" — inconsistent with code's "Enabled by default"
--dns-servers	"auto-detected from host if omitted"	cli-reference.md table says "Auto-detected from host, falls back to 8.8.8.8,8.8.4.4" — consistent with code. AGENTS.md says "Default: Google DNS (8.8.8.8,8.8.4.4)" — may be outdated if auto-detect was added later
--anthropic-cache-tail-ttl	Present in usage.md only in help text printout (line 113)	Not in cli-reference.md options table
--enable-token-steering	In cli-reference.md ✅	usage.md does not have a dedicated section (not found in search)

---

⚠️ Issues Found

Issue 1 — --enable-api-proxy is deprecated but documented as active

Location: docs/usage.md (many lines), docs-site/.../cli-reference.md (line 59, 726+)
Issue: The flag is marked [DEPRECATED] in src/cli-options.ts with the note "The API proxy is always enabled. This flag is ignored." It is also hidden from --help. Despite this, both documentation files document it as a required, actively-used flag with dozens of sudo -E awf --enable-api-proxy ... examples.
Expected: Docs should state that the API proxy is always active; examples should not include --enable-api-proxy; a deprecation/migration notice should be shown.
Current: Both docs treat --enable-api-proxy as an opt-in feature that must be passed for API proxy functionality.
Suggestion: Remove --enable-api-proxy from all examples, add a deprecation callout at the top of the "API Proxy" section, and update the options table to note it is deprecated/ignored.

---

Issue 2 — --network-isolation missing from cli-reference.md

Location: docs-site/src/content/docs/reference/cli-reference.md
Issue: --network-isolation and --no-network-isolation are defined in cli-options.ts (with "Enabled by default") and documented in usage.md, but they do not appear anywhere in the CLI reference options table or as a dedicated section.
Expected: Both flags with their description and defaults should appear in the reference table.
Suggestion: Add entries under the "Network & Security" group in the reference table.

---

Issue 3 — --topology-attach missing from cli-reference.md

Location: docs-site/src/content/docs/reference/cli-reference.md
Issue: --topology-attach is in cli-options.ts and usage.md but absent from the CLI reference.
Suggestion: Add to the reference table with description "Attach external trusted container to internal network (repeatable)".

---

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

Location: docs-site/src/content/docs/reference/cli-reference.md
Issue: Present in cli-options.ts and usage.md but not in CLI reference options table.
Suggestion: Add to the Image Management group in the reference table.

---

Issue 5 — --container-runtime undocumented everywhere

Location: docs/usage.md, docs-site/.../cli-reference.md
Issue: --container-runtime (gvisor/sbx/custom) is defined in cli-options.ts but does not appear in either usage.md or cli-reference.md.
Expected: Flag should be documented with presets gvisor and sbx, and note that custom values are passed through.
Suggestion: Add to both docs under Image Management / Container Configuration.

---

Issue 6 — --vertex-api-target and --vertex-api-base-path undocumented

Location: docs/usage.md, docs-site/.../cli-reference.md
Issue: Both Vertex AI flags are defined in cli-options.ts but appear in neither documentation file. The other provider flags (OpenAI, Anthropic, Gemini) are all documented.
Suggestion: Add --vertex-api-target (default: aiplatform.googleapis.com) and --vertex-api-base-path to both docs alongside the Gemini entries.

---

Issue 7 — --openai-api-auth-header and --anthropic-api-auth-header undocumented

Location: docs/usage.md, docs-site/.../cli-reference.md
Issue: Custom auth header overrides for OpenAI and Anthropic are defined in cli-options.ts but not documented in either file.
Suggestion: Add to both docs in the API Proxy section.

---

Issue 8 — Rate-limit guard flags undocumented (--max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses)

Location: docs/usage.md, docs-site/.../cli-reference.md
Issue: Four flags for automated run-guard behavior are implemented in cli-options.ts but absent from both documentation files.
Suggestion: Add a "Run Guards" subsection in both the API Proxy docs section and the CLI reference, covering all four flags with example values.

---

Issue 9 — --network-isolation described as "Experimental" in usage.md but "Enabled by default" in code

Location: docs/usage.md (line 76)
Issue: usage.md labels --network-isolation as "Experimental" while cli-options.ts notes "Enabled by default (strict security)."
Expected: Documentation should reflect that network isolation is the default, not experimental.
Suggestion: Remove "Experimental" label, update to say "Default behavior — enforces egress via Docker network topology."

---

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

Location: docs-site/src/content/docs/reference/cli-reference.md
Issue: --anthropic-cache-tail-ttl <5m|1h> is in cli-options.ts and mentioned in usage.md's option list printout, but it is absent from the cli-reference.md options table.
Suggestion: Add an entry alongside --anthropic-auto-cache in the reference table.

---

Issue 11 — AGENTS.md states default DNS is Google (8.8.8.8) without noting auto-detection

Location: AGENTS.md (DNS Configuration section)
Issue: AGENTS.md states Default: Google DNS (8.8.8.8,8.8.4.4) but cli-options.ts says DNS is "auto-detected from host if omitted" (with no hard-coded default string).
Expected: Should note that DNS is auto-detected, falling back to 8.8.8.8,8.8.4.4.
Suggestion: Update AGENTS.md to say "Auto-detected from host; falls back to 8.8.8.8,8.8.4.4 if undetectable."

---

Issue 12 — --enable-token-steering missing from usage.md dedicated sections

Location: docs/usage.md
Issue: --enable-token-steering is in the options list in usage.md but does not have its own dedicated section (unlike most other API proxy flags which have dedicated ### headers with examples). cli-reference.md does include it.
Suggestion: Add a dedicated ### --enable-token-steering section with a usage example in usage.md.

---

📋 Recommendations

🔴 High Priority

1. Update --enable-api-proxy deprecation notice — The most widespread issue. Dozens of examples in both docs pass --enable-api-proxy to a flag that is now silently ignored. This will confuse users reading docs. Update all examples, add a deprecation banner at the API Proxy section, and update the options tables.

2. Document --container-runtime — Undocumented in both files. Users running gVisor or microVM sandboxing cannot discover this feature.

3. Document --max-model-multiplier*, --max-permission-denied, --max-cache-misses — Run-guard flags that directly affect billing and security behavior. Critical for operators configuring production deployments.

🟡 Medium Priority

4. Add missing flags to cli-reference.md — --network-isolation, --no-network-isolation, --topology-attach, --docker-host-path-prefix, --anthropic-cache-tail-ttl are all in usage.md but not the CLI reference. The reference should be the canonical single-page reference.

5. Document --vertex-api-target / --vertex-api-base-path — Vertex AI is a major provider; its flags should appear alongside OpenAI/Anthropic/Gemini.

6. Document --openai-api-auth-header / --anthropic-api-auth-header — Custom auth headers for enterprise deployments using non-standard credential formats.

7. Fix --network-isolation "Experimental" label in usage.md — Feature is default-enabled; the "Experimental" label creates false uncertainty.

🟢 Low Priority

8. Add --enable-token-steering section to usage.md — Minor gap; flag exists in the options list but has no examples.

9. Update AGENTS.md DNS default description — Minor text clarification.

---

📁 Files Analyzed

File	Role
src/cli-options.ts	✅ Implementation — source of truth (71 flags)
src/cli.ts	✅ Entry point (delegates to cli-options.ts)
docs/usage.md	✅ User-facing usage guide
docs-site/src/content/docs/reference/cli-reference.md	✅ Detailed CLI reference
README.md	✅ Overview (abbreviated flag list — intentional)
AGENTS.md	✅ Agent/developer instructions

---

Generated by the AWF CLI Flag Consistency Checker — run automatically each week.

Warning

Firewall blocked 1 domain

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

• awmgmcpg

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

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by CLI Flag Consistency Checker · 77.8 AIC · ⊞ 5.6K · ◷

• expires on Jul 27, 2026, 6:23 AM UTC