[CLI Flag Review] Weekly CLI Flag Consistency Report — 2026-04-01

[github-actions[bot]]

Auto-generated by the CLI Flag Consistency Checker workflow · Run #23853628439

📊 Summary

Metric	Count
Total .option() calls in src/cli.ts	61
Flags in docs/usage.md	~38
Flags in docs-site/.../cli-reference.md summary table	~25
Inconsistencies found	12

---

✅ Flag Coverage 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	✅	✅	❌	❌	⚠️ Missing cli-reference
--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 usage.md
--env-file	✅	❌	❌	❌	🔴 Undocumented
-v, --mount	✅	✅	✅	❌	✅ OK
--container-workdir	✅	✅	✅	❌	✅ OK
--memory-limit	✅	✅ (wrong default)	❌	❌	🔴 Wrong default in usage.md
--tty	✅	✅	✅	❌	✅ OK
--dns-servers	✅	✅	✅	❌	✅ OK
--dns-over-https	✅	✅	❌	❌	⚠️ Missing cli-reference
--enable-host-access	✅	✅	✅	❌	✅ OK
--allow-host-ports	✅	✅	✅	❌	✅ OK
--allow-host-service-ports	✅	❌	❌	❌	🔴 Undocumented
--enable-dind	✅	✅	❌	❌	⚠️ Missing cli-reference
--enable-dlp	✅	✅	❌	❌	⚠️ Missing cli-reference
--enable-api-proxy	✅	✅	❌	❌	⚠️ Missing cli-reference table
--copilot-api-target	✅	✅	❌	❌	⚠️ Missing cli-reference
--openai-api-target	✅	✅	❌	❌	⚠️ Missing cli-reference
--openai-api-base-path	✅	❌	❌	❌	🔴 Undocumented
--anthropic-api-target	✅	✅	❌	❌	⚠️ Missing cli-reference
--anthropic-api-base-path	✅	❌	❌	❌	🔴 Undocumented
--rate-limit-rpm	✅	✅	❌	❌	⚠️ Missing cli-reference
--rate-limit-rph	✅	✅	❌	❌	⚠️ Missing cli-reference
--rate-limit-bytes-pm	✅	✅	❌	❌	⚠️ Missing cli-reference
--no-rate-limit	✅	✅	❌	❌	⚠️ Missing cli-reference
--log-level	✅	✅	✅	❌	✅ OK
-k, --keep-containers	✅	✅	✅	❌	✅ OK
--agent-timeout	✅	✅	❌	❌	⚠️ Missing cli-reference
--work-dir	✅	✅	✅	❌	✅ OK
--proxy-logs-dir	✅	✅	✅	❌	✅ OK
--audit-dir	✅	❌	❌	❌	🔴 Undocumented

Subcommands

Subcommand	cli.ts	usage.md	cli-reference.md	Status
predownload	✅	❌	❌	🔴 Undocumented
logs	✅	✅	✅	✅ OK
logs stats	✅	✅	✅	✅ OK
logs summary	✅	✅	✅	✅ OK
logs audit	✅	❌	❌	🔴 Undocumented

---

⚠️ Issues Found

🔴 High Priority

Issue 1 — --memory-limit default mismatch

• Location: docs/usage.md line 83
• Issue: Default value documented incorrectly
• Expected: (default: 6g) — as coded in src/cli.ts:1296
• Current: (default: 2g) in usage.md
• Suggestion: Update usage.md to --memory-limit (limit) Memory limit for the agent container (default: 6g)

Issue 2 — --allow-host-service-ports completely undocumented

• Location: src/cli.ts:1324–1330
• Issue: Flag for allowing ports to the host gateway (for GitHub Actions services) exists in implementation but appears in no documentation
• Description in code: "Ports to allow ONLY to host gateway (for GitHub Actions services). Bypasses dangerous port restrictions. Auto-enables host access. WARNING: Allowing port 22 grants SSH access to the host."
• Suggestion: Add to both usage.md (in the "Network & Security" section near --enable-host-access) and to cli-reference.md summary table. Include the security warning.

Issue 3 — predownload subcommand completely undocumented

• Location: src/cli.ts:1963–1979
• Issue: The awf predownload subcommand for pre-pulling Docker images has no documentation in any user-facing doc
• Options it has: --image-registry, --image-tag, --agent-image, --enable-api-proxy
• Suggestion: Add a ## Subcommands → awf predownload section to cli-reference.md and a note in usage.md

Issue 4 — logs audit subcommand completely undocumented

• Location: src/cli.ts:2066–2096
• Issue: The awf logs audit subcommand is not documented in either usage.md or cli-reference.md
• Options it has: --format, --source, --rule, --domain, --decision
• Suggestion: Add to the subcommands section in cli-reference.md and usage.md

---

🟡 Medium Priority

Issue 5 — --env-file completely undocumented

• Location: src/cli.ts:1279–1282
• Issue: Flag for reading environment variables from a file is not mentioned in any documentation
• Description in code: "Read environment variables from a file (KEY=VALUE format, one per line)"
• Suggestion: Add to both usage.md and cli-reference.md near the --env and --env-all flags

Issue 6 — --audit-dir completely undocumented

• Location: src/cli.ts:1413–1416
• Issue: Flag for saving firewall audit artifacts is not documented anywhere
• Description in code: "Directory for firewall audit artifacts (configs, policy manifest, iptables state)"
• Suggestion: Add to usage.md (Logging & Debug section) and cli-reference.md

Issue 7 — --openai-api-base-path and --anthropic-api-base-path undocumented

• Location: src/cli.ts:1360–1371
• Issue: Both API base path flags exist but appear in no documentation
  • --openai-api-base-path — "Base path prefix for OpenAI API requests (e.g. /serving-endpoints for Databricks)"
  • --anthropic-api-base-path — "Base path prefix for Anthropic API requests (e.g. /anthropic)"
• Suggestion: Add to usage.md API proxy section and cli-reference.md

Issue 8 — --exclude-env missing from usage.md

• Location: src/cli.ts:1273–1278
• Issue: Flag is documented in cli-reference.md but absent from usage.md option listing
• Suggestion: Add --exclude-env (name) to the usage.md options block, near --env-all

---

🔵 Low Priority

Issue 9 — Many flags absent from cli-reference.md summary table

The following flags are documented in usage.md but not in the cli-reference.md summary table:

Flag	Notes
--ruleset-file	YAML-based domain policy files
--memory-limit	Memory cap for agent container
--dns-over-https	DoH sidecar proxy
--enable-dind	Docker-in-Docker
--enable-dlp	Data Loss Prevention scanning
--enable-api-proxy	API proxy sidecar
--copilot-api-target	Copilot API target override
--openai-api-target	OpenAI API target override
--anthropic-api-target	Anthropic API target override
--rate-limit-rpm	Per-provider RPM cap
--rate-limit-rph	Per-provider RPH cap
--rate-limit-bytes-pm	Per-provider bytes-per-minute cap
--no-rate-limit	Disable API proxy rate limiting
--agent-timeout	Max execution time

• Suggestion: Add these to the cli-reference.md Options Summary table with a short description.

Issue 10 — --image-tag description inconsistency within cli.ts

• Location: src/cli.ts:1248–1253 (main command) vs src/cli.ts:1972 (predownload subcommand)
• Issue: Main command description says "applies to both squid and agent images"; predownload says "applies to squid, agent, and api-proxy images"
• Expected: Both should reflect that --image-tag applies to all three images (squid, agent, api-proxy)
• Suggestion: Update main command --image-tag description to say "Container image tag (applies to squid, agent, and api-proxy images)"

---

📋 Recommendations

1. High — Fix --memory-limit default in usage.md: change (default: 2g) → (default: 6g) (src/cli.ts:1296 confirms '6g')
2. High — Document predownload and logs audit subcommands in cli-reference.md and usage.md
3. High — Document --allow-host-service-ports with its security warning in both docs
4. Medium — Add --env-file, --audit-dir, --openai-api-base-path, --anthropic-api-base-path to docs
5. Medium — Add --exclude-env to usage.md option listing (already in cli-reference.md)
6. Low — Expand cli-reference.md summary table to include the ~14 flags currently omitted
7. Low — Fix --image-tag description in main command to mention all three images (not just squid/agent)

---

📁 Files Analyzed

File	Purpose	Status
src/cli.ts	Implementation (source of truth)	61 .option() calls, 5 subcommands
docs/usage.md	User-facing usage guide	~38 flags, missing 6
docs-site/src/content/docs/reference/cli-reference.md	CLI reference	~25 flags in table, missing ~14
README.md	Project overview	Minimal flags (by design)
AGENTS.md	Agent instructions	Flags mentioned appear correct
CLAUDE.md	Claude-specific instructions	Flags mentioned appear correct

AI generated by CLI Flag Consistency Checker

• expires on Apr 8, 2026, 2:35 PM UTC