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

[github-actions[bot]]

📊 Summary

Metric	Count
Total flags in src/cli.ts	52
Flags documented in docs/usage.md	37 / 52
Flags documented in cli-reference.md	43 / 52
Default value mismatches	1
Missing from usage.md	15
Missing from cli-reference.md	9

---

✅ Flags Status

Main Command Flags

Flag	cli.ts	usage.md	cli-reference.md	README.md	Status
--config <path>	✅	❌	❌	❌	⚠️ Missing docs
-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
--docker-host	✅	❌	❌	❌	⚠️ Missing docs
-e, --env	✅	✅	✅	❌	✅ OK
--env-all	✅	✅	✅	❌	✅ OK
--exclude-env	✅	❌	✅	❌	⚠️ Missing from usage.md
--env-file	✅	❌	✅	❌	⚠️ Missing from usage.md
-v, --mount	✅	✅	✅	❌	✅ OK
--container-workdir	✅	✅	✅	❌	✅ OK
--memory-limit	✅	✅ (wrong default)	✅	❌	❌ Default mismatch
--tty	✅	✅	✅	❌	✅ OK
--dns-servers	✅	✅	✅	❌	✅ OK
--dns-over-https	✅	✅	✅	❌	✅ OK
--upstream-proxy	✅	❌	❌	❌	⚠️ Missing docs
--enable-host-access	✅	✅	✅	❌	✅ OK
--allow-host-ports	✅	✅	✅	❌	✅ OK
--allow-host-service-ports	✅	❌	✅	❌	⚠️ Missing from 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 from usage.md
--anthropic-api-target	✅	✅	✅	❌	✅ OK
--anthropic-api-base-path	✅	❌	✅	❌	⚠️ Missing from usage.md
--gemini-api-target	✅	❌	❌	❌	⚠️ Missing docs
--gemini-api-base-path	✅	❌	❌	❌	⚠️ Missing docs
--rate-limit-rpm	✅	✅	✅	❌	✅ OK
--rate-limit-rph	✅	✅	✅	❌	✅ OK
--rate-limit-bytes-pm	✅	✅	✅	❌	✅ OK
--no-rate-limit	✅	✅	✅	❌	✅ OK
--difc-proxy-host	✅	❌	❌	❌	⚠️ Missing docs
--difc-proxy-ca-cert	✅	❌	❌	❌	⚠️ Missing docs
--log-level	✅	✅	✅	❌	✅ OK
-k, --keep-containers	✅	✅	✅	❌	✅ OK
--agent-timeout	✅	✅	✅	❌	✅ OK
--work-dir	✅	✅	✅	❌	✅ OK
--proxy-logs-dir	✅	✅	✅	❌	✅ OK
--audit-dir	✅	❌	✅	❌	⚠️ Missing from usage.md
--session-state-dir	✅	✅	✅	❌	✅ OK
--diagnostic-logs	✅	❌	❌	❌	⚠️ Missing docs

Subcommands

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

---

⚠️ Issues Found

🔴 High Priority

Issue 1: --memory-limit default value mismatch

• Location: docs/usage.md line 89
• Issue: Default value documented incorrectly
• Current: (default: 2g)
• Expected: (default: 6g) — matches src/cli.ts line 1427: '6g' and cli-reference.md line 44
• Suggestion: Update docs/usage.md line 89 to show (default: 6g)

Issue 2: --gemini-api-target and --gemini-api-base-path undocumented

• Location: Both docs/usage.md and cli-reference.md
• Issue: Gemini API proxy target flags added to src/cli.ts (lines 1508–1515) but not mentioned in either doc file
• Suggestion: Add alongside the existing --openai-api-target, --anthropic-api-target sections in both files

Issue 3: --difc-proxy-host and --difc-proxy-ca-cert undocumented

• Location: Both docs/usage.md and cli-reference.md
• Issue: DIFC proxy flags defined in src/cli.ts (lines 1534–1543) have no user-facing documentation
• Suggestion: Add a "DIFC / External CLI Proxy" section in both docs; cross-reference --enable-api-proxy where relevant

Issue 4: --config <path> undocumented

• Location: Both docs/usage.md and cli-reference.md
• Issue: The --config <path> flag (reads JSON/YAML config file or stdin) is defined in src/cli.ts line 1303–1306 but absent from all doc files
• Suggestion: Add a "Configuration file" section describing the --config flag and noting it can accept - for stdin

---

🟡 Medium Priority

Issue 5: --diagnostic-logs undocumented

• Location: Both docs/usage.md and cli-reference.md
• Issue: Flag defined in src/cli.ts lines 1577–1583 for collecting container diagnostics on non-zero exit; not in any public doc
• Suggestion: Add to the "Logging & Debug" section in both docs

Issue 6: --docker-host undocumented

• Location: Both docs/usage.md and cli-reference.md
• Issue: Flag defined in src/cli.ts lines 1385–1390 but not documented
• Suggestion: Add to "Image Management" section; useful for non-standard Docker socket paths

Issue 7: --upstream-proxy undocumented

• Location: Both docs/usage.md and cli-reference.md
• Issue: Corporate/upstream proxy chaining flag defined in src/cli.ts lines 1444–1449 but not in docs
• Suggestion: Add to "Network & Security" section; note auto-detection from host https_proxy/http_proxy

Issue 8: --exclude-env and --env-file missing from docs/usage.md

• Location: docs/usage.md (both are present in cli-reference.md)
• Issue: These flags appear in cli-reference.md but were never added to the usage.md options list
• Suggestion: Add both to the usage.md options block alongside --env-all

Issue 9: --openai-api-base-path and --anthropic-api-base-path missing from docs/usage.md

• Location: docs/usage.md (both are present in cli-reference.md)
• Issue: Base path override flags for API proxy not in the usage.md option list
• Suggestion: Add alongside the --openai-api-target / --anthropic-api-target entries in usage.md

Issue 10: --allow-host-service-ports and --audit-dir missing from docs/usage.md

• Location: docs/usage.md (both are present in cli-reference.md)
• Issue: Flags present in cli-reference.md but not in usage.md option list
• Suggestion: Add to usage.md option block

---

🟢 Low Priority

Issue 11: awf predownload subcommand missing from docs/usage.md

• Location: docs/usage.md
• Issue: awf predownload is documented in cli-reference.md (line 950) but completely absent from usage.md
• Suggestion: Add a brief "Pre-downloading images" section to usage.md

Issue 12: awf logs audit subcommand missing from docs/usage.md

• Location: docs/usage.md
• Issue: awf logs audit is documented in cli-reference.md (line 1185) but not in usage.md, which only covers logs stats and logs summary
• Suggestion: Add awf logs audit usage and examples to docs/usage.md

Issue 13: predownload --difc-proxy option undocumented

• Location: Both docs/usage.md and cli-reference.md
• Issue: predownload subcommand has a --difc-proxy flag (src/cli.ts line 2286) not mentioned in cli-reference.md's predownload section
• Suggestion: Add --difc-proxy to the predownload options table in cli-reference.md

Issue 14: AGENTS.md / CLAUDE.md examples missing -- separator

• Location: AGENTS.md lines 129, 383, 388, 392, 516 (identical file content as CLAUDE.md)
• Issue: Several code examples omit the -- separator before the agent command, inconsistent with the canonical usage shown in README.md (sudo awf --allow-domains github.com -- curl ...)
• Examples affected:
  • awf --allow-domains github.com 'curl https://api.github.com'
  • awf --allow-domains github.com \ "npx @github/copilot@0.0.347 ..."
• Suggestion: Add -- separator to all examples in AGENTS.md/CLAUDE.md for consistency

---

📋 Recommendations

High Priority

1. Fix --memory-limit default value in docs/usage.md (2g → 6g) — quick one-line fix
2. Document --gemini-api-target / --gemini-api-base-path in both usage.md and cli-reference.md
3. Document --difc-proxy-host / --difc-proxy-ca-cert in both files
4. Document --config <path> in both files

Medium Priority

5. Add --diagnostic-logs, --docker-host, --upstream-proxy to both doc files
6. Sync usage.md to include the 4 flags already in cli-reference.md but missing from usage.md: --exclude-env, --env-file, --openai-api-base-path, --anthropic-api-base-path, --allow-host-service-ports, --audit-dir

Low Priority

7. Add predownload and logs audit subcommand sections to docs/usage.md
8. Add --difc-proxy to the predownload options in cli-reference.md
9. Update AGENTS.md / CLAUDE.md examples to use -- separator consistently

---

📁 Files Analyzed

File	Purpose	Status
src/cli.ts	Implementation (source of truth)	52 flags + 5 subcommands identified
docs/usage.md	User-facing usage guide	37/52 flags covered; 1 default wrong
docs-site/src/content/docs/reference/cli-reference.md	Detailed CLI reference	43/52 flags covered
README.md	Project overview	Only references core flags; acceptable
AGENTS.md	Agent instructions	References key flags; minor example inconsistencies
CLAUDE.md	Agent instructions (identical content)	Same as AGENTS.md

Generated by CLI Flag Consistency Checker · ● 763.3K · ◷

• expires on Apr 26, 2026, 10:16 PM UTC