[CLI Flag Review] Weekly Report

[github-actions[bot]]

📊 Summary

• Total flags in implementation: 103
• Total flags documented (in at least one doc): 86
• Inconsistencies found: 25

✅ Flags Status

Flag	cli.ts/cli-options.ts	usage.md	cli-reference.md	README.md	Status
--config	✅	✅	✅	✅	✅ OK
-d, --allow-domains	✅	✅	✅	✅	✅ OK
--allow-domains-file	✅	✅	✅	❌	⚠️ README missing
--ruleset-file	✅	✅	✅	❌	⚠️ README missing
--block-domains	✅	✅	✅	❌	⚠️ README missing
--block-domains-file	✅	✅	✅	❌	⚠️ README missing
--ssl-bump	✅	✅	✅	✅	✅ OK
--allow-urls	✅	✅	✅	✅	✅ OK
-b, --build-local	✅	✅	✅	❌	⚠️ README only mentions in prose/examples
--agent-image	✅	✅	✅	❌	⚠️ README missing
--image-registry	✅	✅	✅	❌	⚠️ README missing
--image-tag	✅	✅	✅	❌	⚠️ README missing
--skip-pull	✅	✅	✅	❌	⚠️ README missing
--docker-host	✅	✅	✅	❌	⚠️ README missing
--docker-host-path-prefix	✅	✅	❌	❌	⚠️ Missing from cli-reference
--container-runtime	✅	❌	❌	❌	⚠️ Undocumented advanced flag
--cloud-hypervisor-preview	✅	❌	❌	❌	i️ Preview/advanced; absent from user-facing flag docs
--cloud-hypervisor-binary	✅	❌	❌	❌	i️ Preview/advanced
--cloud-hypervisor-kernel	✅	❌	❌	❌	i️ Preview/advanced
--cloud-hypervisor-rootfs	✅	❌	❌	❌	i️ Preview/advanced
--cloud-hypervisor-supervisor	✅	❌	❌	❌	i️ Preview/advanced
--cloud-hypervisor-vcpus	✅	❌	❌	❌	i️ Preview/advanced
--cloud-hypervisor-memory-mib	✅	❌	❌	❌	i️ Preview/advanced
--cloud-hypervisor-api-timeout-ms	✅	❌	❌	❌	i️ Preview/advanced
--cloud-hypervisor-*-sha256	✅	❌	❌	❌	i️ Preview digest flags undocumented
-e, --env	✅	✅	✅	❌	⚠️ README missing
--env-all	✅	✅	✅	❌	⚠️ README missing
--exclude-env	✅	✅	✅	❌	⚠️ README missing
--env-file	✅	✅	✅	❌	⚠️ README missing
-v, --mount	✅	✅	✅	❌	⚠️ README missing
--container-workdir	✅	✅	✅	❌	⚠️ cli-reference default inconsistent
--memory-limit	✅	✅	✅	❌	⚠️ README missing
--pids-limit	✅	✅	❌	❌	⚠️ Missing from cli-reference
--tty	✅	✅	✅	❌	⚠️ README missing
--dns-servers	✅	✅	✅	❌	⚠️ CLAUDE default outdated
--dns-over-https	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--upstream-proxy	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--enable-host-access	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--network-isolation	✅	✅	❌	❌	⚠️ Missing from cli-reference; usage default outdated
--no-network-isolation	✅	❌	❌	❌	⚠️ Undocumented companion flag
--topology-attach	✅	✅	❌	❌	⚠️ Missing from cli-reference
--allow-host-ports	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--allow-host-service-ports	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--enable-dind	✅	✅	✅	✅	✅ OK
--legacy-security	✅	✅	❌	❌	⚠️ Missing from cli-reference
--security-mode	✅	❌	❌	❌	i️ Hidden deprecated flag
--enable-dlp	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--enable-api-proxy	✅	✅	✅	❌	⚠️ Docs stale: implementation says deprecated/always enabled
--no-enable-api-proxy	✅	❌	❌	❌	i️ Hidden removed flag
--copilot-api-target	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--openai-api-target	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--openai-base-url-env	✅	❌	✅	❌	⚠️ Missing from usage.md
--openai-api-base-path	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--anthropic-api-target	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--anthropic-api-base-path	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--openai-api-auth-header	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--anthropic-api-auth-header	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--gemini-api-target	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--gemini-api-base-path	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--vertex-api-target	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--vertex-api-base-path	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--anthropic-auto-cache	✅	✅	❌	❌	⚠️ Missing from cli-reference
--anthropic-cache-tail-ttl	✅	✅	❌	❌	⚠️ Missing from cli-reference
--rate-limit-rpm	✅	✅	✅	❌	⚠️ cli-reference default likely stale/unsupported
--rate-limit-rph	✅	✅	✅	❌	⚠️ cli-reference default likely stale/unsupported
--rate-limit-bytes-pm	✅	✅	✅	❌	⚠️ cli-reference default likely stale/unsupported
--no-rate-limit	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--max-model-multiplier	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--max-model-multiplier-cap	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--max-permission-denied	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--max-cache-misses	✅	❌	❌	❌	⚠️ Undocumented implemented flag
--enable-token-steering	✅	❌	✅	❌	⚠️ Missing from usage.md
--difc-proxy-host	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--difc-proxy-ca-cert	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--log-level	✅	✅	✅	✅	✅ OK
-k, --keep-containers	✅	✅	✅	✅	✅ OK
--agent-timeout	✅	✅	✅	✅	✅ OK
--work-dir	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--proxy-logs-dir	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--audit-dir	✅	✅	✅	✅	✅ OK
--session-state-dir	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--diagnostic-logs	✅	✅	✅	❌	⚠️ README/CLAUDE missing
--reflect	✅	❌	❌	✅	⚠️ Only README documents it
predownload --image-registry	✅	✅	✅	❌	⚠️ README only mentions subcommand
predownload --image-tag	✅	✅	✅	❌	⚠️ README only mentions subcommand
predownload --agent-image	✅	✅	✅	❌	⚠️ README only mentions subcommand
predownload --enable-api-proxy	✅	✅	✅	❌	⚠️ Subcommand documented; semantics stale elsewhere
predownload --difc-proxy	✅	✅	✅	❌	⚠️ README only mentions subcommand
predownload --config	✅	❌	✅	❌	⚠️ Missing from usage.md
logs -f, --follow	✅	✅	✅	✅	✅ OK
logs --format	✅	✅	✅	✅	✅ OK
logs --source	✅	✅	✅	✅	✅ OK
logs --list	✅	✅	✅	✅	✅ OK
logs --with-pid	✅	✅	✅	✅	✅ OK
logs stats --format	✅	✅	✅	✅	✅ OK
logs stats --source	✅	✅	✅	✅	✅ OK
logs summary --format	✅	✅	✅	✅	✅ OK
logs summary --source	✅	✅	✅	✅	✅ OK
logs audit --format	✅	✅	✅	✅	✅ OK
logs audit --source	✅	✅	✅	✅	✅ OK
logs audit --rule	✅	✅	✅	✅	✅ OK
logs audit --domain	✅	✅	✅	✅	✅ OK
logs audit --decision	✅	✅	✅	✅	✅ OK

⚠️ Issues Found

Location	Issue	Expected	Current	Suggestion
docs/usage.md, docs-site/.../cli-reference.md, CLAUDE.md	--enable-api-proxy semantics are stale	Docs should say API proxy is always enabled / flag deprecated or ignored	Docs still describe it as optional, default false, and enabling sidecar behavior	Update all docs to match implementation; mention hidden --no-enable-api-proxy is removed/erroring
docs/usage.md	--network-isolation default is outdated	Default should reflect implementation/help text (“enabled by default”)	Usage guide says (default: false) and labels it experimental	Rewrite section around strict/default behavior and explain --legacy-security / --no-network-isolation
docs-site/src/content/docs/reference/cli-reference.md	Missing --network-isolation, --topology-attach, --legacy-security, --pids-limit, --docker-host-path-prefix	Reference should list these implemented public flags	Entirely absent from options summary/details	Add summary rows and detailed sections
docs/usage.md	Missing --openai-base-url-env	Usage guide should cover implemented OpenAI-compatible secret base URL flow	Present only in cli-reference	Add option to command list and API proxy section
docs-site/src/content/docs/reference/cli-reference.md	Missing --anthropic-auto-cache and --anthropic-cache-tail-ttl	Both implemented API-proxy flags should be documented	Absent from summary/details	Add both with requires/default notes
docs/usage.md	Missing --enable-token-steering	Usage guide should include implemented token steering flag	Present in cli-reference only	Add option text and API proxy example
docs/usage.md, docs-site/.../cli-reference.md	--reflect missing from detailed docs	Flag should be discoverable in usage/reference docs	Only README mentions awf --reflect	Add to main options list/details
docs-site/src/content/docs/reference/cli-reference.md	--container-workdir default is likely wrong	No explicit default in CLI option, or actual runtime default if resolved elsewhere	Reference says default is User home	Verify actual runtime default and either document accurately or remove default claim
docs-site/src/content/docs/reference/cli-reference.md	Rate-limit defaults may be stale/invented	Only document defaults if they come from CLI/runtime config	Lists 600, 10000, 52428800, but CLI option declarations set no defaults	Verify runtime defaults; otherwise change to “unset / runtime default”
CLAUDE.md	DNS default text is outdated	Should mention auto-detect from host if omitted, fallback to Google DNS	Says default is Google DNS	Update to match implementation and usage/reference docs
docs/usage.md	Missing predownload --config	Subcommand docs should cover all implemented options	predownload --config absent	Add to subcommand options block
docs-site/src/content/docs/reference/cli-reference.md	Missing implemented auth-header/provider flags	--openai-api-auth-header, --anthropic-api-auth-header, --vertex-api-target, --vertex-api-base-path should either be documented or explicitly hidden/internal	Not documented anywhere user-facing	Decide whether to document or hide from CLI help if internal
docs-site/src/content/docs/reference/cli-reference.md, docs/usage.md	Missing implemented limit flags	--max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses should be documented if public	Not documented anywhere	Add advanced API-proxy limits section or hide if internal
README.md	Main README coverage is very thin for many public flags	README can stay concise, but should not imply obsolete semantics	Many current flags absent; --enable-api-proxy not mentioned while README still highlights optional sidecar	At minimum add note that full docs live in usage/reference, and remove outdated optional-sidecar framing
AGENTS.md	File missing	If intended as a documentation source, it should exist	No AGENTS.md found at repo root	Either create it or remove it from future audit scope

📋 Recommendations

• High

  1. Update --enable-api-proxy docs everywhere to match implementation (deprecated/always enabled).
  2. Fix strict security docs: --network-isolation default behavior, --legacy-security, and --no-network-isolation.
  3. Bring cli-reference.md back to parity for missing public flags: --docker-host-path-prefix, --pids-limit, --topology-attach, API-proxy cache/limit flags, and --reflect.
  4. Audit documented defaults in cli-reference.md; remove any value not actually sourced from code/runtime (--container-workdir, rate-limit defaults).

• Medium

  1. Add missing usage.md entries for --openai-base-url-env, --enable-token-steering, predownload --config, and --reflect.
  2. Decide whether auth-header / Vertex / model-limit flags are public. If yes, document them; if not, hide them from help.
  3. Update CLAUDE.md to reflect current defaults and API-proxy behavior.

• Low

  1. Keep README concise, but add a short “advanced flags live in docs/usage.md and cli-reference.md” note.
  2. Consider labeling cloud-hypervisor flags explicitly as preview/internal in docs rather than leaving them entirely implicit.
  3. Add a generated CLI-doc sync check in CI to catch future drift.

📁 Files Analyzed

• src/cli-options.ts
• src/commands/subcommands.ts
• docs/usage.md
• docs-site/src/content/docs/reference/cli-reference.md
• README.md
• CLAUDE.md
• AGENTS.md (not present at repository root)

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

• expires on Aug 31, 2026, 6:07 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-31T18:07:30.689Z.

Closed by Workflow