[CLI Flag Review] CLI Flag Consistency Report — Weekly Audit (2026-04-12)

[github-actions[bot]]

📊 Summary

Analysis of AWF CLI flag consistency across src/cli.ts (source of truth) and documentation files.

Metric	Count
Total flags in src/cli.ts (main command)	49
Total subcommand-specific flags	17
Inconsistencies found	18
Files analyzed	6

---

✅ Flags Status

Main Command Flags

Flag	cli.ts	usage.md	cli-reference.md	README.md	Status
-d, --allow-domains	✅	✅	✅	✅	✅ OK
--allow-domains-file	✅	✅	✅	❌	✅ OK
--ruleset-file	✅	✅	✅	❌	✅ OK
--block-domains	✅	✅	✅	❌	✅ OK
--block-domains-file	✅	✅	✅	❌	✅ OK
--ssl-bump	✅	✅	✅	❌	✅ OK
--allow-urls	✅	✅	✅	❌	✅ OK
-b, --build-local	✅	✅	✅	✅	✅ OK
--agent-image	✅	✅	✅	❌	✅ OK
--image-registry	✅	✅	✅	✅	✅ OK
--image-tag	✅	✅	✅	✅	✅ OK
--skip-pull	✅	✅	✅	✅	✅ OK
-e, --env	✅	✅	✅	❌	✅ OK
--env-all	✅	✅	✅	❌	✅ OK
--exclude-env	✅	❌	✅	❌	⚠️ Missing in usage.md
--env-file	✅	❌	✅	❌	⚠️ Missing in usage.md
-v, --mount	✅	✅	✅	❌	✅ OK
--container-workdir	✅	✅	✅	❌	✅ OK
--memory-limit	✅	⚠️ wrong default	✅	❌	❌ Wrong default in usage.md
--tty	✅	✅	✅	❌	✅ OK
--dns-servers	✅	⚠️ wrong default	✅	✅	⚠️ Misleading default in usage.md
--dns-over-https	✅	✅	✅	❌	✅ OK
--enable-host-access	✅	✅	✅	❌	✅ OK
--allow-host-ports	✅	✅	✅	✅	✅ OK
--allow-host-service-ports	✅	❌	✅	❌	⚠️ Missing in usage.md
--enable-dind	✅	✅	✅	❌	✅ OK
--enable-dlp	✅	✅	✅	❌	✅ OK
--enable-api-proxy	✅	✅	✅	✅	✅ OK
--copilot-api-target	✅	✅	✅	❌	✅ OK
--openai-api-target	✅	✅	✅	❌	✅ OK
--openai-api-base-path	✅	❌	✅	❌	⚠️ Missing in usage.md
--anthropic-api-target	✅	✅	✅	❌	✅ OK
--anthropic-api-base-path	✅	❌	✅	❌	⚠️ Missing in usage.md
--gemini-api-target	✅	❌	❌	❌	❌ Missing in all docs
--gemini-api-base-path	✅	❌	❌	❌	❌ Missing in all docs
--rate-limit-rpm	✅	✅	✅	❌	✅ OK
--rate-limit-rph	✅	✅	✅	❌	✅ OK
--rate-limit-bytes-pm	✅	✅	✅	❌	✅ OK
--no-rate-limit	✅	✅	✅	❌	✅ OK
--difc-proxy-host	✅	❌	❌	❌	❌ Missing in all docs
--difc-proxy-ca-cert	✅	❌	❌	❌	❌ Missing in all docs
--log-level	✅	✅	✅	❌	✅ OK
-k, --keep-containers	✅	✅	✅	❌	✅ OK
--agent-timeout	✅	✅	✅	❌	✅ OK
--work-dir	✅	✅	✅	❌	✅ OK
--proxy-logs-dir	✅	✅	✅	❌	✅ OK
--audit-dir	✅	❌	✅	❌	⚠️ Missing in usage.md
--session-state-dir	✅	✅	❌	❌	⚠️ Missing in cli-reference.md options table
--diagnostic-logs	✅	❌	❌	❌	❌ Missing in all docs

predownload Subcommand Flags

Flag	cli.ts	usage.md	cli-reference.md	Status
--image-registry	✅	❌	✅	⚠️ predownload not in usage.md
--image-tag	✅	❌	✅	⚠️ predownload not in usage.md
--agent-image	✅	❌	✅	⚠️ predownload not in usage.md
--enable-api-proxy	✅	❌	✅	⚠️ predownload not in usage.md
--difc-proxy	✅	❌	❌	❌ Missing everywhere

logs Subcommand Flags

Flag	cli.ts	usage.md	cli-reference.md	Status
-f, --follow	✅	✅	✅	✅ OK
--format	✅	✅	✅	✅ OK
--source	✅	✅	✅	✅ OK
--list	✅	✅	✅	✅ OK
--with-pid	✅	✅	✅	✅ OK
logs stats --format	✅	✅	✅	✅ OK
logs stats --source	✅	✅	✅	✅ OK
logs summary --format	✅	✅	✅	✅ OK
logs summary --source	✅	✅	✅	✅ OK
logs audit --format	✅	❌	✅	⚠️ logs audit not in usage.md
logs audit --source	✅	❌	✅	⚠️ logs audit not in usage.md
logs audit --rule	✅	❌	✅	⚠️ logs audit not in usage.md
logs audit --domain	✅	❌	✅	⚠️ logs audit not in usage.md
logs audit --decision	✅	❌	✅	⚠️ logs audit not in usage.md

---

⚠️ Issues Found

Issue 1 — Wrong Default Value: --memory-limit in docs/usage.md

• Location: docs/usage.md, line 86
• Issue: Memory limit default is documented as 2g but the implementation default is 6g
• Current: --memory-limit <limit> Memory limit for the agent container (default: 2g)
• Expected: (default: 6g) — matches src/cli.ts:1409 and cli-reference.md
• Suggestion: Update line 86 of docs/usage.md to say (default: 6g)

---

Issue 2 — Misleading Default: --dns-servers in docs/usage.md

• Location: docs/usage.md, lines 52–54
• Issue: usage.md says default: 8.8.8.8,8.8.4.4 but cli.ts auto-detects from host with no hardcoded fallback specified in .option(). The cli-reference.md correctly says "Auto-detected".
• Current: DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4)
• Expected: Describe auto-detection behavior, with 8.8.8.8,8.8.4.4 as fallback (not primary default)
• Suggestion: Update docs/usage.md to match cli-reference.md wording: "Auto-detected from host; falls back to 8.8.8.8,8.8.4.4"

---

Issue 3 — Missing Flags in docs/usage.md Options Table

The following flags exist in src/cli.ts but are absent from the options table in docs/usage.md:

Flag	Notes
--exclude-env	Documented in cli-reference.md
--env-file	Documented in cli-reference.md
--allow-host-service-ports	Documented in cli-reference.md with full section
--openai-api-base-path	Documented in cli-reference.md
--anthropic-api-base-path	Documented in cli-reference.md
--audit-dir	Documented in cli-reference.md with full section

Suggestion: Add these six flags to the docs/usage.md options table.

---

Issue 4 — --gemini-api-target and --gemini-api-base-path Missing from All Docs

• Location: src/cli.ts:1485–1491
• Issue: Gemini API target and base-path flags are defined in the implementation but absent from docs/usage.md, docs-site/src/content/docs/reference/cli-reference.md, README.md, AGENTS.md, and CLAUDE.md
• Suggestion: Add --gemini-api-target and --gemini-api-base-path to the options table and API proxy sections in both docs/usage.md and cli-reference.md (alongside the OpenAI and Anthropic equivalents)

---

Issue 5 — --difc-proxy-host and --difc-proxy-ca-cert Missing from All Docs

• Location: src/cli.ts:1510–1520
• Issue: DIFC proxy flags are defined in the implementation but absent from all documentation files
• Suggestion: Add a "CLI Proxy (DIFC)" section to both docs/usage.md and cli-reference.md documenting both flags and their relationship to the external DIFC proxy

---

Issue 6 — --diagnostic-logs Missing from All Docs

• Location: src/cli.ts:1553–1559
• Issue: The --diagnostic-logs flag is defined in the implementation but absent from all documentation
• Suggestion: Add --diagnostic-logs to the "Logging & Debug" section in both docs/usage.md and cli-reference.md

---

Issue 7 — --session-state-dir Missing from cli-reference.md Options Summary Table

• Location: docs-site/src/content/docs/reference/cli-reference.md options summary table
• Issue: --session-state-dir is documented in docs/usage.md (line 56) and has substantial detail in docs/usage.md (lines 890–918), but is absent from the options summary table in cli-reference.md
• Suggestion: Add --session-state-dir to the options summary table in cli-reference.md

---

Issue 8 — predownload Subcommand Missing from docs/usage.md

• Location: docs/usage.md
• Issue: The predownload subcommand is fully documented in cli-reference.md (section at line 940) but has zero coverage in docs/usage.md
• Suggestion: Add a "Subcommands" section to docs/usage.md covering predownload and its options

---

Issue 9 — logs audit Subcommand Missing from docs/usage.md

• Location: docs/usage.md, Commands section (lines 99–113)
• Issue: The Commands section in docs/usage.md lists logs, logs stats, and logs summary, but omits logs audit. cli-reference.md has a full awf logs audit section (line 1175)
• Suggestion: Add logs audit to the Commands listing in docs/usage.md with its options (--format, --source, --rule, --domain, --decision)

---

Issue 10 — --difc-proxy Flag for predownload Missing Everywhere

• Location: src/cli.ts:2202
• Issue: The predownload subcommand has a --difc-proxy flag (to pre-download the CLI proxy image), but this flag is absent from cli-reference.md's predownload options table and all other docs
• Suggestion: Add --difc-proxy to the predownload options table in cli-reference.md

---

📋 Recommendations

🔴 High Priority

1. Fix --memory-limit default in docs/usage.md — The documented default of 2g is factually wrong; the implementation default is 6g. This will confuse users who rely on default behavior. (Issue 1)

2. Document --gemini-api-target and --gemini-api-base-path — These flags exist alongside OpenAI and Anthropic equivalents, but are invisible to users reading any documentation. (Issue 4)

3. Document --difc-proxy-host and --difc-proxy-ca-cert — These flags enable a significant security feature (external DIFC proxy). Without documentation, they are effectively undiscoverable. (Issue 5)

🟡 Medium Priority

4. Document --diagnostic-logs — Useful debugging flag that is completely undocumented. (Issue 6)

5. Add missing flags to docs/usage.md options table — Six flags (--exclude-env, --env-file, --allow-host-service-ports, --openai-api-base-path, --anthropic-api-base-path, --audit-dir) are in cli-reference.md but missing from usage.md. (Issue 3)

6. Add predownload subcommand to docs/usage.md — Currently only documented in cli-reference.md. (Issue 8)

7. Add logs audit to docs/usage.md Commands section — The other three logs subcommands are all listed; audit is missing. (Issue 9)

🟢 Low Priority

8. Fix --dns-servers default description in docs/usage.md to clarify auto-detection. (Issue 2)

9. Add --session-state-dir to cli-reference.md options summary table — It's in the file body but missing from the quick-reference table. (Issue 7)

10. Add --difc-proxy to predownload options table in cli-reference.md. (Issue 10)

---

📁 Files Analyzed

File	Role
src/cli.ts	✅ Implementation (source of truth)
docs/usage.md	✅ User-facing usage guide (1128 lines)
docs-site/src/content/docs/reference/cli-reference.md	✅ Detailed CLI reference (1247 lines)
README.md	✅ Quick start / overview (63 lines)
AGENTS.md	✅ Agent instructions (588 lines)
CLAUDE.md	✅ Agent instructions (588 lines)

Note: AGENTS.md and CLAUDE.md reference flags only in examples and commands, which is appropriate for agent instruction files. No flag inconsistencies were found in these files beyond the above.

Generated by CLI Flag Consistency Checker · ● 1.2M · ◷

• expires on Apr 19, 2026, 10:07 PM UTC

[github-actions[bot]]

🔮 The ancient spirits stir in the firewall veil.
The smoke-test wanderer has crossed this discussion.
May allowed domains stay true, and denied paths fade to mist.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

🔮 The ancient spirits stir in the halls of automation.
The smoke-test wanderer has passed through this thread,
and the runes record: the oracle agent was here.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

🔮 The ancient spirits stir in the firewall halls.
The smoke-test oracle has passed through this thread,
tracing codepaths, runes, and network wards.
May the next invocation be swift and true.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

🔮 The ancient spirits stir through the firewall paths.
The smoke-test agent has walked this thread and left a trace in the ether.
May the wards hold, and the packets flow only where permitted.

🔮 The oracle has spoken through Smoke Codex