[CLI Flag Review] CLI Flag Consistency Report — 2026-03-18

[github-actions[bot]]

Weekly automated analysis comparing src/cli.ts against all documentation files.

---

📊 Summary

Metric	Count
Total flags in src/cli.ts (main command)	37
Additional flags across subcommands (predownload, logs, logs stats, logs summary)	13
Total CLI surface	50
Flags fully covered in cli-reference.md	~21 / 37 main flags
Flags fully covered in docs/usage.md	~27 / 37 main flags
Distinct issues found	~22

---

✅ Flags Coverage Status (Main Command)

Flag	cli.ts	docs/usage.md	cli-reference.md	README.md	Status
-d, --allow-domains	✅	✅	✅	✅	✅ OK
--allow-domains-file	✅	✅	✅	➖	✅ OK
--ruleset-file	✅	❌	❌	❌	⚠️ Missing docs
--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	✅	✅	✅	➖	⚠️ Description inconsistency (see Issues)
--skip-pull	✅	✅	✅	➖	✅ OK
-e, --env	✅	✅	✅	➖	✅ OK
--env-all	✅	✅	✅	➖	✅ OK
-v, --mount	✅	✅	✅	➖	✅ OK
--container-workdir	✅	✅	✅	➖	✅ OK
--memory-limit	✅	❌	❌	❌	⚠️ Missing docs
--tty	✅	✅	✅	➖	✅ OK
--dns-servers	✅	✅	✅	➖	✅ OK
--dns-over-https	✅	❌	❌	❌	⚠️ Missing docs
--enable-host-access	✅	✅	✅	➖	✅ OK
--allow-host-ports	✅	✅	✅	➖	✅ OK
--enable-dind	✅	❌	❌	❌	⚠️ Missing docs
--enable-dlp	✅	❌	❌	❌	⚠️ Missing docs
--enable-api-proxy	✅	✅	❌	➖	⚠️ Missing from cli-reference.md
--copilot-api-target	✅	❌	❌	❌	⚠️ Missing docs
--openai-api-target	✅	❌	❌	❌	⚠️ Missing docs
--anthropic-api-target	✅	❌	❌	❌	⚠️ Missing docs
--rate-limit-rpm	✅	✅ (example only)	❌	❌	⚠️ Missing from cli-reference.md
--rate-limit-rph	✅	✅ (example only)	❌	❌	⚠️ Missing from cli-reference.md
--rate-limit-bytes-pm	✅	❌	❌	❌	⚠️ Missing docs
--no-rate-limit	✅	❌	❌	❌	⚠️ Missing docs
--log-level	✅	✅	✅	➖	✅ OK
-k, --keep-containers	✅	✅	✅	➖	✅ OK
--agent-timeout	✅	✅	❌	❌	⚠️ Missing from cli-reference.md
--work-dir	✅	✅	✅	➖	✅ OK
--proxy-logs-dir	✅	✅	✅	➖	✅ OK

➖ README.md is an overview file; it intentionally omits most flags.

Subcommand Coverage

Subcommand	cli.ts	docs/usage.md	cli-reference.md	Status
awf predownload	✅	❌	❌	⚠️ Missing from all docs
awf logs	✅	✅	✅	✅ OK
awf logs stats	✅	✅	✅	✅ OK
awf logs summary	✅	✅	✅	✅ OK

---

⚠️ Issues Found

Issue 1 — --keep-containers cleanup note uses wrong container name

• Location: docs-site/src/content/docs/reference/cli-reference.md, line 171
• Issue: Cleanup command references non-existent container awf-copilot
• Current: docker stop awf-squid awf-copilot && docker network rm awf-net
• Expected: docker stop awf-squid awf-agent && docker network rm awf-net
• Evidence: src/docker-manager.ts defines container_name: 'awf-agent' (line 955); awf-copilot does not exist

---

Issue 2 — --image-tag description is inconsistent between main command and predownload

• Location: src/cli.ts, line 1179 vs line 1839
• Issue: The main command option says "applies to both squid and agent images", but the predownload subcommand says "applies to squid, agent, and api-proxy images". The main option description is outdated — --image-tag also applies to the api-proxy image.
• Current (main): 'Container image tag (applies to both squid and agent images)'
• Expected: 'Container image tag (applies to squid, agent, and api-proxy images)'

---

Issue 3 — --ruleset-file not documented anywhere

• Location: src/cli.ts, line 1131; absent from all documentation
• Issue: YAML rule file for domain allowlisting is completely undocumented
• Implementation: 'YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}]'
• Suggestion: Add to cli-reference.md summary table and docs/usage.md Domain Whitelisting section

---

Issue 4 — --memory-limit not documented anywhere

• Location: src/cli.ts, line 1213; absent from all documentation
• Issue: Memory limit for the agent container is completely undocumented
• Implementation: 'Memory limit for the agent container (e.g., 1g, 2g, 4g, 512m). Default: 2g', default '2g'
• Suggestion: Add to cli-reference.md summary table under Container Configuration, and to docs/usage.md

---

Issue 5 — --dns-over-https not documented anywhere

• Location: src/cli.ts, line 1231; absent from all documentation
• Issue: DNS-over-HTTPS sidecar proxy option is completely undocumented
• Implementation: `'Enable DNS-over-HTTPS via sidecar proxy (default: (dns.google/redacted), optional resolver URL
• Suggestion: Add to both cli-reference.md and docs/usage.md Network & Security sections

---

Issue 6 — --enable-dind not documented anywhere

• Location: src/cli.ts, line 1246; absent from all documentation
• Issue: Docker-in-Docker option (with its security warning) is completely undocumented
• Implementation: 'Enable Docker-in-Docker by exposing host Docker socket. WARNING: allows firewall bypass via docker run'
• Suggestion: Add to cli-reference.md and docs/usage.md with a security caution

---

Issue 7 — --enable-dlp not documented in user-facing docs

• Location: src/cli.ts, line 1252; absent from docs/usage.md and cli-reference.md
• Issue: DLP (Data Loss Prevention) URL scanning flag is not in user-facing documentation (only mentioned in AGENTS.md technical notes)
• Implementation: 'Enable DLP (Data Loss Prevention) scanning to block credential exfiltration in outbound request URLs.'
• Suggestion: Add to cli-reference.md summary table and add a docs/usage.md section

---

Issue 8 — --enable-api-proxy missing from cli-reference.md summary table

• Location: docs-site/src/content/docs/reference/cli-reference.md, lines 20-46
• Issue: --enable-api-proxy is present in docs/usage.md but not in the cli-reference.md Options Summary table, and there are no sections for any of the related API Proxy flags
• Missing from cli-reference.md: --enable-api-proxy, --copilot-api-target, --openai-api-target, --anthropic-api-target, --rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm, --no-rate-limit
• Suggestion: Add an "API Proxy" section to cli-reference.md covering all 8 flags

---

Issue 9 — --copilot-api-target, --openai-api-target, --anthropic-api-target not documented in user-facing docs

• Location: src/cli.ts, lines 1265–1276; absent from both docs/usage.md and cli-reference.md
• Issue: API target override flags have no documentation. Users who need GHEC or custom endpoints cannot discover these flags.
• Suggestion: Add to both documentation files under the API Proxy Sidecar section

---

Issue 10 — --rate-limit-bytes-pm and --no-rate-limit not documented anywhere

• Location: src/cli.ts, lines 1285-1292; absent from all documentation
• --rate-limit-bytes-pm: 'Max request bytes per minute per provider (requires --enable-api-proxy)'
• --no-rate-limit: 'Disable rate limiting in the API proxy (requires --enable-api-proxy)'
• Suggestion: Add to cli-reference.md and docs/usage.md API Proxy sections

---

Issue 11 — --agent-timeout missing from cli-reference.md

• Location: docs-site/src/content/docs/reference/cli-reference.md; present in docs/usage.md line 24 (in help text block only)
• Issue: --agent-timeout is shown in usage.md's help text block but never explained, and is completely absent from cli-reference.md
• Implementation: 'Maximum time in minutes for the agent command to run (default: no limit)'
• Suggestion: Add to cli-reference.md summary table and Logging & Debug section

---

Issue 12 — predownload subcommand not documented

• Location: src/cli.ts, line 1832; absent from docs/usage.md and cli-reference.md
• Issue: The awf predownload subcommand for pre-pulling Docker images is completely absent from all user-facing docs. Its options (--image-registry, --image-tag, --agent-image, --enable-api-proxy) are only described indirectly via the main command flags.
• Suggestion: Add a predownload subcommand section to cli-reference.md Subcommands section and mention it in docs/usage.md

---

📋 Recommendations

🔴 High Priority

1. Fix incorrect container name in cli-reference.md line 171: replace awf-copilot → awf-agent
2. Add --enable-api-proxy and all API Proxy flags to cli-reference.md — these flags (--enable-api-proxy, --copilot-api-target, --openai-api-target, --anthropic-api-target, --rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm, --no-rate-limit) are entirely missing from the reference doc
3. Document predownload subcommand in cli-reference.md and docs/usage.md

🟡 Medium Priority

4. Add --memory-limit to both cli-reference.md and docs/usage.md — users may hit OOM errors without knowing this exists (default: 2g)
5. Add --agent-timeout to cli-reference.md — present in usage.md help text but unexplained
6. Add --enable-dlp to user-facing docs with a security explanation
7. Add --dns-over-https to both docs with usage examples
8. Add --ruleset-file to both docs with schema example
9. Fix --image-tag description in src/cli.ts line 1179: "both squid and agent" → "squid, agent, and api-proxy"

🟢 Low Priority

10. Add --enable-dind with prominent security warning to both docs
11. Document --rate-limit-bytes-pm and --no-rate-limit in the API Proxy sections

---

📁 Files Analyzed

File	Lines	Role
src/cli.ts	1936	✅ Implementation (source of truth)
docs/usage.md	1054	✅ User guide
docs-site/src/content/docs/reference/cli-reference.md	577	✅ CLI reference
README.md	63	✅ Overview (intentionally minimal)
AGENTS.md	~590	✅ Developer/agent instructions
CLAUDE.md	588	✅ Developer/agent instructions

AI generated by CLI Flag Consistency Checker

• expires on Mar 25, 2026, 2:34 PM UTC