[CLI Flag Review] CLI Flag Consistency Report — Weekly Review

[github-actions[bot]]

📊 Summary

Metric	Count
Total flags in src/cli.ts (main command)	40
Total subcommands	5 (predownload, logs, logs stats, logs summary, logs audit)
Flags fully documented (usage.md + cli-reference.md)	24
Flags with incomplete/missing documentation	16
Subcommands missing documentation	2
Description/naming errors	3

---

✅ Flags Status

Flag	src/cli.ts	docs/usage.md	cli-reference.md	README.md	Status
-d, --allow-domains	✅	✅	✅ (missing -d alias)	✅	⚠️ Alias missing from ref table
--allow-domains-file	✅	✅	✅	—	✅ OK
--ruleset-file	✅	❌	❌	❌	❌ Undocumented
--block-domains	✅	✅	✅	—	✅ OK
--block-domains-file	✅	✅	✅	—	✅ OK
--ssl-bump	✅	✅	✅	—	✅ OK
--allow-urls	✅	✅	✅	—	✅ OK
-b, --build-local	✅	✅	✅ (missing -b alias)	✅	⚠️ Alias missing from ref table
--agent-image	✅	✅	✅	—	✅ OK
--image-registry	✅	✅	✅	—	✅ OK
--image-tag	✅	✅	✅	—	✅ OK
--skip-pull	✅	✅	✅	—	✅ OK
-e, --env	✅	✅	✅	—	✅ OK
--env-all	✅	✅	✅	—	✅ OK
-v, --mount	✅	✅	✅	—	✅ OK
--container-workdir	✅	✅	✅	—	✅ OK
--memory-limit	✅	❌	❌	❌	❌ Undocumented
--tty	✅	✅	✅	—	✅ OK
--dns-servers	✅	✅	✅	—	✅ OK
--dns-over-https	✅	❌	❌	❌	❌ Undocumented
--enable-host-access	✅	✅	✅	—	✅ OK
--allow-host-ports	✅	✅	✅	—	✅ OK
--enable-dind	✅	❌	❌	❌	❌ Undocumented
--enable-dlp	✅	❌	❌	❌	❌ Undocumented
--enable-api-proxy	✅	✅	✅	—	✅ OK
--copilot-api-target	✅	❌	❌	❌	❌ Undocumented
--openai-api-target	✅	❌	❌	❌	❌ Undocumented
--openai-api-base-path	✅	❌	❌	❌	❌ Undocumented
--anthropic-api-target	✅	❌	❌	❌	❌ Undocumented
--anthropic-api-base-path	✅	❌	❌	❌	❌ Undocumented
--rate-limit-rpm	✅	⚠️ (example only)	❌	❌	⚠️ In example, not in options table
--rate-limit-rph	✅	⚠️ (example only)	❌	❌	⚠️ In example, not in options table
--rate-limit-bytes-pm	✅	❌	❌	❌	❌ Undocumented
--no-rate-limit	✅	❌	❌	❌	❌ Undocumented
--log-level	✅	✅	✅	—	✅ OK
-k, --keep-containers	✅	✅	✅ (missing -k alias)	—	⚠️ Alias missing from ref table
--agent-timeout	✅	✅	❌	❌	⚠️ Missing from cli-reference.md table
--work-dir	✅	✅	✅	—	✅ OK
--proxy-logs-dir	✅	✅	✅	—	✅ OK
--audit-dir	✅	❌	❌	❌	❌ Undocumented

Subcommands Status

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

---

⚠️ Issues Found

🔴 High Priority — Completely Undocumented Flags

1. --ruleset-file (path) — No documentation anywhere

• Location: src/cli.ts:1132–1136
• Issue: Flag exists in implementation with a description but appears in no documentation file.
• Expected: Entry in docs/usage.md options block and cli-reference.md options table.
• Current: Absent from all documentation.
• Suggestion: Add under a "Domain Filtering" section. Description from code: "YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}]"

2. --memory-limit (limit) — No documentation anywhere

• Location: src/cli.ts:1214–1218
• Issue: Flag with default 6g and description "Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g" has no documentation.
• Expected: Entry in options tables in both docs.
• Suggestion: Add under a "Container Configuration" section.

3. --dns-over-https [resolver-url] — No documentation anywhere

• Location: src/cli.ts:1231–1234
• Issue: An optional-value flag enabling DNS-over-HTTPS via sidecar proxy is completely undocumented.
• Expected: Entry in options tables; note the unusual optional-value syntax [resolver-url].
• Suggestion: Document alongside --dns-servers with a note about the default resolver URL (`(dns.google/redacted)

4. --enable-dind — No user-facing docs (mentioned only in AGENTS.md)

• Location: src/cli.ts:1246–1251
• Issue: Flag exists with a security warning in the description but is absent from user-facing docs.
• Current: Only referenced in AGENTS.md as architectural background.
• Suggestion: Add a short entry (with the security warning) to docs/usage.md and the cli-reference table. This flag is security-sensitive and users should understand the risks.

5. --enable-dlp — No user-facing docs (mentioned only in AGENTS.md)

• Location: src/cli.ts:1252–1257
• Issue: Data Loss Prevention scanning flag has no user documentation.
• Current: Only referenced in AGENTS.md.
• Suggestion: Document in docs/usage.md and cli-reference.md. Consider a dedicated section explaining what patterns are scanned.

6. --copilot-api-target, --openai-api-target, --anthropic-api-target — No documentation

• Location: src/cli.ts:1266–1281
• Issue: All three API target override flags are undocumented. These are important for GHEC and enterprise customers routing traffic to custom endpoints.
• Suggestion: Document in docs/usage.md under the API Proxy section, and add to cli-reference.md options table. Also reference from docs/enterprise-configuration.md.

7. --openai-api-base-path, --anthropic-api-base-path — No documentation

• Location: src/cli.ts:1274–1285
• Issue: Base-path overrides for API proxy (e.g., Databricks /serving-endpoints) are completely undocumented.
• Suggestion: Document alongside the API target flags above.

8. --rate-limit-bytes-pm (n) — No documentation

• Location: src/cli.ts:1294–1297
• Issue: While --rate-limit-rpm and --rate-limit-rph appear in docs/usage.md examples, the bytes-per-minute rate limit flag is entirely absent.
• Suggestion: Add all three rate limit flags (rpm, rph, bytes-pm) to a table in docs/usage.md and cli-reference.md options table.

9. --no-rate-limit — No documentation

• Location: src/cli.ts:1298–1301
• Issue: The escape hatch to disable API proxy rate limiting is undocumented.
• Suggestion: Document alongside the rate limit flags.

10. --audit-dir (path) — No documentation

• Location: src/cli.ts:1327–1330
• Issue: Flag for saving firewall audit artifacts (configs, policy manifest, iptables state) is entirely undocumented.
• Suggestion: Add to docs/usage.md and cli-reference.md, especially important given it works with logs audit.

11. predownload subcommand — No documentation

• Location: src/cli.ts:1850–1866
• Issue: The predownload subcommand (pre-pull container images for offline use) is not mentioned in any documentation.
• Suggestion: Add a section to docs/usage.md and an entry in cli-reference.md under Subcommands. Include its flags: --image-registry, --image-tag, --agent-image, --enable-api-proxy.

12. logs audit subcommand — No documentation

• Location: src/cli.ts:1953–1983
• Issue: The awf logs audit subcommand (firewall audit with policy rule matching) is absent from all documentation.
• Suggestion: Add to docs/usage.md and cli-reference.md alongside the other logs subcommands. Document its options: --format, --source, --rule, --domain, --decision.

---

🟡 Medium Priority — Incomplete Documentation

13. --rate-limit-rpm and --rate-limit-rph — Examples-only, no options table entry

• Location: docs/usage.md:454–455 (usage example only)
• Issue: These two flags appear only in a bash example block but never in any options table or detailed description.
• Expected: Entries in the docs/usage.md options block and cli-reference.md options table.
• Suggestion: Add to both options tables with their types (integer), defaults (none), and a note that they require --enable-api-proxy.

14. --agent-timeout (minutes) — Missing from cli-reference.md

• Location: docs/usage.md:24 (present); cli-reference.md options table (absent)
• Issue: --agent-timeout appears in docs/usage.md's help-block reproduction but has no entry in the cli-reference.md Options Summary table or any detailed subsection.
• Suggestion: Add a row to the cli-reference.md Options Summary table and a ### --agent-timeout subsection.

---

🟠 Naming / Accuracy Errors

15. Wrong container name in --keep-containers note (cli-reference.md)

• Location: docs-site/src/content/docs/reference/cli-reference.md:171
• Issue: The note says docker stop awf-squid awf-copilot && docker network rm awf-net but the agent container is named awf-agent, not awf-copilot.
• Expected: docker stop awf-squid awf-agent && docker network rm awf-net
• Current: docker stop awf-squid awf-copilot && docker network rm awf-net
• Suggestion: Fix the container name. This would cause confusion/failure for users following the cleanup instructions.

16. Short aliases -d and -b missing from cli-reference.md options table

• Location: docs-site/src/content/docs/reference/cli-reference.md Options Summary table
• Issue: The options table shows --allow-domains and --build-local without their short aliases (-d and -b respectively). The table correctly includes -e and -v but is inconsistent about other aliases.
• Suggestion: Update table entries to \-d, --allow-domains (domains)`and`-b, --build-local``.

17. --image-registry parameter name inconsistency

• Location: cli-reference.md Options Summary row
• Issue: cli-reference.md shows --image-registry (url) but src/cli.ts uses (registry) as the metavar. This is a minor cosmetic inconsistency.
• Suggestion: Align to --image-registry (registry) (as in cli.ts) for consistency.

---

📋 Recommendations

🔴 High Priority (Fix Soon)

1. Fix wrong container name in cli-reference.md:171 — awf-copilot → awf-agent. This is an actionable error that will break user workflows.
2. Document --ruleset-file — Policy-as-code feature for domain allowlisting; important for enterprise users.
3. Document predownload subcommand — Needed by users in air-gapped or pre-warmed environments.
4. Document logs audit subcommand — Completes the logs subcommand family and pairs with --audit-dir.

🟡 Medium Priority (Next Docs Pass)

5. Document API proxy customization flags (--copilot-api-target, --openai-api-target, --openai-api-base-path, --anthropic-api-target, --anthropic-api-base-path) — Critical for GHEC/enterprise configurations.
6. Add rate limit flags to options tables — --rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm, --no-rate-limit should all appear in the options summary, not just in examples.
7. Document --audit-dir — Pairs with logs audit for audit workflows.
8. Document --memory-limit — Users hitting OOM errors would not know this is tunable.
9. Add --agent-timeout to cli-reference.md table.

🟢 Low Priority (Polish)

10. Document --dns-over-https — Niche but useful for restricted environments.
11. Document --enable-dind and --enable-dlp — Even a brief mention with security caveats is better than silence.
12. Add short aliases to cli-reference.md — Add -d for --allow-domains and -b for --build-local to the options table.
13. Standardize --image-registry metavar — Minor: change (url) → (registry).

---

📁 Files Analyzed

File	Lines	Notes
src/cli.ts	1,986	Implementation — source of truth
docs/usage.md	1,054	Primary user guide
docs-site/src/content/docs/reference/cli-reference.md	577	Docs-site reference
README.md	63	High-level overview only; not expected to cover all flags
AGENTS.md	588	Agent instructions; some flags mentioned in passing
CLAUDE.md	(not in repo root; checked AGENTS.md)	—

AI generated by CLI Flag Consistency Checker

• expires on Apr 1, 2026, 2:28 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-04-01T14:28:33.374Z.

Closed by Workflow