[CLI Flag Review] Weekly Analysis

[github-actions[bot]]

Automated weekly analysis comparing the AWF CLI implementation (src/cli-options.ts, src/commands/subcommands.ts) against user-facing docs (docs/usage.md, docs-site/.../cli-reference.md, README.md, AGENTS.md, CLAUDE.md).

📊 Summary

• Implementation flags found: 102 total
  • Main command (src/cli-options.ts): 85
  • Subcommand options (src/commands/subcommands.ts): 17
• Documented flags found (union across requested docs): 75
• Inconsistencies found: 28 notable items
• Nuance: many advanced/internal flags are intentionally omitted from README.md, AGENTS.md, and CLAUDE.md; treated as soft gaps, not hard errors. The main hard comparisons are against docs/usage.md and especially docs-site/.../cli-reference.md.

✅ Flags Status

Flag	cli-options.ts	usage.md	cli-reference.md	README.md	Status
--config <path>	✅	✅	✅	✅	✅ OK
-d, --allow-domains <domains>	✅	✅	✅	✅	✅ OK
--allow-domains-file <path>	✅	✅	✅	❌	✅ OK
--ruleset-file <path>	✅	✅	✅	❌	✅ OK
--block-domains <domains>	✅	✅	✅	❌	✅ OK
--block-domains-file <path>	✅	✅	✅	❌	✅ OK
--ssl-bump	✅	✅	✅	✅	✅ OK
--allow-urls <urls>	✅	✅	✅	✅	✅ OK
-b, --build-local	✅	✅	✅	✅	✅ OK
--agent-image <value>	✅	✅	✅	❌	✅ OK
--image-registry <registry>	✅	✅	✅	❌	✅ OK
--image-tag <tag>	✅	✅	✅	❌	✅ OK
--skip-pull	✅	✅	✅	❌	✅ OK
--docker-host <socket>	✅	✅	✅	❌	✅ OK
--docker-host-path-prefix <prefix>	✅	✅	❌	❌	⚠️ Missing from cli-reference
--container-runtime <runtime>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-preview	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-mount-policy <policy>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-binary <path>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-kernel <path>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-rootfs <path>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-supervisor <path>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-artifact-manifest <path>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-artifact-manifest-bundle <path>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-artifact-release-tag <tag>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-development-allow-unattested-artifacts	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-vcpus <count>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-memory-mib <mib>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-api-timeout-ms <ms>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-binary-sha256 <digest>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-virtiofsd-sha256 <digest>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-kernel-sha256 <digest>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-rootfs-sha256 <digest>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-supervisor-sha256 <digest>	✅	❌	❌	❌	⚠️ Undocumented advanced flag
-e, --env <KEY=VALUE>	✅	✅	✅	❌	✅ OK
--env-all	✅	✅	✅	❌	✅ OK
--exclude-env <name>	✅	✅	✅	❌	✅ OK
--env-file <path>	✅	✅	✅	❌	✅ OK
-v, --mount <host_path:container_path[:mode]>	✅	✅	✅	❌	✅ OK
--container-workdir <dir>	✅	✅	✅	❌	⚠️ Default mismatch in cli-reference
--memory-limit <limit>	✅	✅	✅	❌	✅ OK
--pids-limit <limit>	✅	✅	❌	❌	⚠️ Missing from cli-reference
--tty	✅	✅	✅	❌	✅ OK
--dns-servers <servers>	✅	✅	✅	❌	⚠️ Default wording mismatch in AGENTS/CLAUDE
--dns-over-https [resolver-url]	✅	✅	✅	❌	✅ OK
--upstream-proxy <url>	✅	✅	✅	❌	✅ OK
--enable-host-access	✅	✅	✅	❌	⚠️ Description mismatch in docs
--network-isolation	✅	✅	❌	❌	⚠️ Missing from cli-reference
--no-network-isolation	✅	❌	❌	❌	⚠️ Undocumented
--topology-attach <name>	✅	✅	❌	❌	⚠️ Missing from cli-reference
--allow-host-ports <ports>	✅	✅	✅	❌	⚠️ Default mismatch in usage/cli-reference
--allow-host-service-ports <ports>	✅	✅	✅	❌	✅ OK
--enable-dind	✅	✅	✅	❌	✅ OK
--legacy-security	✅	✅	❌	❌	⚠️ Missing from cli-reference
--security-mode <mode>	✅	❌	❌	❌	⚠️ Hidden/deprecated undocumented
--enable-dlp	✅	✅	✅	✅	✅ OK
--enable-api-proxy	✅	✅	✅	❌	⚠️ Docs stale: deprecated/always-enabled in code
--no-enable-api-proxy	✅	❌	❌	❌	⚠️ Removed-flag behavior undocumented
--copilot-api-target <host>	✅	✅	✅	❌	✅ OK
--openai-api-target <host>	✅	✅	✅	❌	✅ OK
--openai-base-url-env <name>	✅	❌	✅	❌	⚠️ Missing from usage.md
--openai-api-base-path <path>	✅	✅	✅	❌	✅ OK
--anthropic-api-target <host>	✅	✅	✅	❌	✅ OK
--anthropic-api-base-path <path>	✅	✅	✅	❌	✅ OK
--openai-api-auth-header <name>	✅	❌	❌	❌	⚠️ Undocumented
--anthropic-api-auth-header <name>	✅	❌	❌	❌	⚠️ Undocumented
--gemini-api-target <host>	✅	✅	✅	❌	✅ OK
--gemini-api-base-path <path>	✅	✅	✅	❌	✅ OK
--vertex-api-target <host>	✅	❌	❌	❌	⚠️ Undocumented
--vertex-api-base-path <path>	✅	❌	❌	❌	⚠️ Undocumented
--api-proxy-ca-cert <path>	✅	❌	✅	❌	⚠️ Missing from usage.md
--anthropic-auto-cache	✅	✅	❌	❌	⚠️ Missing from cli-reference
--anthropic-cache-tail-ttl <5m|1h>	✅	✅	❌	❌	⚠️ Missing from cli-reference
--rate-limit-rpm <n>	✅	✅	✅	❌	⚠️ Default mismatch in cli-reference
--rate-limit-rph <n>	✅	✅	✅	❌	⚠️ Default mismatch in cli-reference
--rate-limit-bytes-pm <n>	✅	✅	✅	❌	⚠️ Default mismatch in cli-reference
--no-rate-limit	✅	✅	✅	❌	✅ OK
--max-model-multiplier <model:multiplier,...>	✅	❌	❌	❌	⚠️ Undocumented
--max-model-multiplier-cap <number>	✅	❌	❌	❌	⚠️ Undocumented
--max-permission-denied <number>	✅	❌	❌	❌	⚠️ Undocumented
--max-cache-misses <number>	✅	❌	❌	❌	⚠️ Undocumented
--enable-token-steering	✅	❌	✅	❌	⚠️ Missing from usage.md
--difc-proxy-host <host:port>	✅	✅	✅	❌	✅ OK
--difc-proxy-ca-cert <path>	✅	✅	✅	❌	✅ OK
--log-level <level>	✅	✅	✅	❌	✅ OK
-k, --keep-containers	✅	✅	✅	❌	✅ OK
--agent-timeout <minutes>	✅	✅	✅	❌	✅ OK
--work-dir <dir>	✅	✅	✅	❌	✅ OK
--proxy-logs-dir <path>	✅	✅	✅	❌	✅ OK
--audit-dir <path>	✅	✅	✅	✅	✅ OK
--session-state-dir <path>	✅	✅	✅	❌	✅ OK
--diagnostic-logs	✅	✅	✅	❌	✅ OK
--reflect	✅	❌	❌	✅	⚠️ Missing from primary docs
predownload --image-registry <registry>	✅	✅	✅	❌	✅ OK
predownload --image-tag <tag>	✅	✅	✅	❌	✅ OK
predownload --agent-image <value>	✅	✅	✅	❌	✅ OK
predownload --enable-api-proxy	✅	✅	✅	❌	⚠️ Semantics stale relative to main flag deprecation
predownload --difc-proxy	✅	✅	✅	❌	✅ OK
predownload --config <path>	✅	❌	❌	❌	⚠️ Subcommand option undocumented
logs -f, --follow	✅	✅	✅	❌	✅ OK
logs --format <format>	✅	✅	✅	❌	✅ OK
logs --source <path>	✅	✅	✅	❌	✅ OK
logs --list	✅	✅	✅	❌	✅ OK
logs --with-pid	✅	✅	✅	❌	⚠️ Description wording differs slightly
logs stats --format <format>	✅	✅	✅	❌	✅ OK
logs stats --source <path>	✅	✅	✅	❌	✅ OK
logs summary --format <format>	✅	✅	✅	❌	✅ OK
logs summary --source <path>	✅	✅	✅	❌	✅ OK
logs audit --format <format>	✅	✅	✅	❌	✅ OK
logs audit --source <path>	✅	✅	✅	❌	✅ OK
logs audit --rule <id>	✅	✅	✅	❌	✅ OK
logs audit --domain <domain>	✅	✅	✅	❌	✅ OK
logs audit --decision <decision>	✅	✅	✅	❌	✅ OK

⚠️ Issues Found

1) Hard doc gaps in the canonical CLI reference

Location: docs-site/src/content/docs/reference/cli-reference.md
Issue: Missing implemented flags: --docker-host-path-prefix, --pids-limit, --network-isolation, --topology-attach, --legacy-security, --anthropic-auto-cache, --anthropic-cache-tail-ttl, predownload --config.
Expected: Full reference should cover every supported public flag, especially advanced ones.
Current: These flags exist in code and partly in docs/usage.md, but not in the reference.
Suggestion: Add explicit entries and detail sections, or mark them intentionally internal if that is the product decision.

2) Entire advanced flag families are undocumented

Location: docs/usage.md, cli-reference.md, README
Issue: No documentation for --container-runtime, all --cloud-hypervisor-* flags, --openai-api-auth-header, --anthropic-api-auth-header, --vertex-api-target, --vertex-api-base-path, --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses, --no-network-isolation, --security-mode (hidden/deprecated).
Expected: Either documented in the reference or clearly designated hidden/internal-only.
Current: They are implemented and user-settable but absent from docs.
Suggestion: Decide which are public. Document public ones in cli-reference.md; hide/internalize the rest consistently.

3) --enable-api-proxy docs are stale

Location: docs/usage.md, cli-reference.md, AGENTS.md, CLAUDE.md
Issue: Docs describe it as enabling an optional sidecar, but code marks it deprecated/ignored on the main command ([DEPRECATED] The API proxy is always enabled. This flag is ignored.); --no-enable-api-proxy is defined as removed/error; subcommand predownload --enable-api-proxy is still meaningful.
Expected: Main-command docs should say always enabled / deprecated flag ignored.
Current: Docs still describe opt-in behavior.
Suggestion: Split semantics clearly — main command: deprecated, always on; predownload: still meaningful for image pull selection.

4) --reflect is only surfaced in README

Location: docs/usage.md, cli-reference.md
Issue: Implemented flag missing from both main docs.
Expected: Present in usage and reference, especially because README advertises it.
Current: Only README mentions it.
Suggestion: Add option entry and example.

5) Default-value mismatches for host-access behavior

Location: docs/usage.md, cli-reference.md
Issue: Docs say --allow-host-ports defaults to 80,443 and imply --enable-host-access permits only 80/443 by default; other prose in usage.md says "all ports currently allowed."
Expected: One authoritative description matching implementation.
Current: Internal contradiction across sections.
Suggestion: Reconcile host-access semantics and update all sections together.

6) Rate-limit defaults overstated in reference

Location: cli-reference.md
Issue: Reference lists concrete defaults (--rate-limit-rpm=600, --rate-limit-rph=10000, --rate-limit-bytes-pm=52428800), but code does not define CLI defaults in .option(...); later prose says defaults apply only "when rate limiting is enabled."
Expected: Default column should reflect CLI default accurately, likely "—" or "applies when feature enabled."
Current: Table implies unconditional CLI defaults.
Suggestion: Clarify "effective runtime default when enabled," not "Commander default."

7) --container-workdir default mismatch

Location: cli-reference.md
Issue: Reference says default is "User home." Code defines no commander default.
Expected: Either "—" or a precise runtime-derived default if guaranteed elsewhere.
Suggestion: Change default column or annotate as runtime behavior.

8) Missing short aliases in reference/README

Location: cli-reference.md, README
Issue: Short forms absent or inconsistently surfaced: -d/--allow-domains, -b/--build-local, -e/--env, -v/--mount, -k/--keep-containers, -f/logs --follow.
Suggestion: Normalize tables to include full short/long forms.

9) Subcommand doc gap: predownload --config

Location: docs/usage.md, cli-reference.md
Issue: Implemented in src/commands/subcommands.ts but not documented.
Suggestion: Add to both subcommand docs, noting it pulls only pinned images declared by container.images.

10) AGENTS.md / CLAUDE.md contain stale architectural flag semantics

Location: AGENTS.md, CLAUDE.md
Issue: Both still describe API proxy as optional and enabled via --enable-api-proxy; DNS section says default is Google DNS, while code auto-detects from host if omitted.
Suggestion: Refresh those files to match current defaults and deprecations.

📋 Recommendations

High Priority

1. Update cli-reference.md to be truly exhaustive for all public flags, especially advanced/runtime flags.
2. Fix --enable-api-proxy documentation everywhere to reflect main-command deprecation and always-enabled behavior.
3. Document --reflect and predownload --config in both usage.md and cli-reference.md.

Medium Priority
4. Resolve default mismatches for --allow-host-ports, --container-workdir, and rate-limit flags.
5. Add missing short aliases to cli-reference.md.
6. Decide public vs internal status for Cloud Hypervisor, runtime, Vertex, auth-header, and token-budget flags.

Low Priority
7. Refresh README/AGENTS/CLAUDE wording so architectural summaries stop describing superseded behavior.
8. Add an "advanced/internal flags" section if intentional omission from beginner docs is desired.

📁 Files Analyzed

• src/cli-options.ts
• src/commands/subcommands.ts
• docs/usage.md
• docs-site/src/content/docs/reference/cli-reference.md
• README.md
• AGENTS.md
• CLAUDE.md

Generated by CLI Flag Consistency Checker · copilot · auto · 58.1 AIC · ⊞ 9.8K · ◷

• expires on Sep 7, 2026, 6:09 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-09-07T18:09:54.917Z.

Closed by Workflow