[CLI Flag Review] Weekly CLI Flag Consistency Report — 2026-07-12

[github-actions[bot]]

📊 Summary

Weekly automated consistency check between src/cli-options.ts (implementation) and user-facing documentation.

• Total flags in implementation (src/cli-options.ts): 67
• Flags fully documented in both docs/usage.md and cli-reference.md: 58
• Flags missing from documentation: 9
• Description/default discrepancies: 2
• Total issues found: 11

---

✅ Flags Status

Flag	cli-options.ts	usage.md	cli-reference.md	README.md	Status
--config	✅	✅	✅	✅	✅ OK
-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	✅	✅	✅	✅	✅ OK
--docker-host-path-prefix	✅	✅	✅	✅	✅ OK
--container-runtime	✅	❌	❌	❌	⚠️ Missing docs
-e, --env	✅	✅	✅	✅	✅ OK
--env-all	✅	✅	✅	✅	✅ OK
--exclude-env	✅	✅	✅	✅	✅ OK
--env-file	✅	✅	✅	✅	✅ OK
-v, --mount	✅	✅	✅	✅	✅ OK
--container-workdir	✅	✅	✅	✅	✅ OK
--memory-limit	✅	✅	✅	✅	✅ OK
--tty	✅	✅	✅	✅	✅ OK
--dns-servers	✅	✅	✅	✅	✅ OK
--dns-over-https	✅	✅	✅	✅	✅ OK
--upstream-proxy	✅	✅	✅	✅	✅ OK
--enable-host-access	✅	✅	✅	✅	✅ OK
--network-isolation	✅	✅	✅	✅	✅ OK
--topology-attach	✅	✅	✅	✅	✅ OK
--allow-host-ports	✅	✅	✅	✅	✅ OK
--allow-host-service-ports	✅	✅	✅	✅	✅ OK
--enable-dind	✅	✅	✅	✅	✅ OK
--enable-dlp	✅	✅	✅	✅	✅ OK
--enable-api-proxy	✅	✅	✅	✅	✅ OK
--copilot-api-target	✅	✅	✅	✅	✅ OK
--openai-api-target	✅	✅	✅	✅	✅ OK
--openai-api-base-path	✅	✅	✅	✅	✅ OK
--anthropic-api-target	✅	✅	✅	✅	✅ OK
--anthropic-api-base-path	✅	✅	✅	✅	✅ OK
--openai-api-auth-header	✅	❌	❌	❌	⚠️ Missing docs
--anthropic-api-auth-header	✅	❌	❌	❌	⚠️ Missing docs
--gemini-api-target	✅	✅	✅	✅	✅ OK
--gemini-api-base-path	✅	✅	✅	✅	✅ OK
--vertex-api-target	✅	❌	❌	❌	⚠️ Missing docs
--vertex-api-base-path	✅	❌	❌	❌	⚠️ Missing docs
--anthropic-auto-cache	✅	✅	✅	✅	✅ OK
--anthropic-cache-tail-ttl	✅	✅	✅	✅	✅ OK
--rate-limit-rpm	✅	✅	✅	✅	✅ OK
--rate-limit-rph	✅	✅	✅	✅	✅ OK
--rate-limit-bytes-pm	✅	✅	✅	✅	✅ OK
--no-rate-limit	✅	✅	✅	✅	✅ OK
--max-model-multiplier	✅	❌	❌	❌	⚠️ Missing docs
--max-model-multiplier-cap	✅	❌	❌	❌	⚠️ Missing docs
--max-permission-denied	✅	❌	❌	❌	⚠️ Missing docs
--max-cache-misses	✅	❌	❌	❌	⚠️ Missing docs
--enable-token-steering	✅	✅	✅	✅	✅ OK
--difc-proxy-host	✅	✅	✅	✅	✅ OK
--difc-proxy-ca-cert	✅	✅	✅	✅	✅ OK
--log-level	✅	✅	✅	✅	✅ OK
-k, --keep-containers	✅	✅	✅	✅	✅ OK
--agent-timeout	✅	✅	✅	✅	✅ OK
--work-dir	✅	✅	✅	✅	✅ OK
--proxy-logs-dir	✅	✅	✅	✅	✅ OK
--audit-dir	✅	✅	✅	✅	✅ OK
--session-state-dir	✅	✅	✅	✅	✅ OK
--diagnostic-logs	✅	✅	✅	✅	✅ OK

---

⚠️ Issues Found

Issue 1 — --container-runtime not documented anywhere

• Location: src/cli-options.ts (defined), absent from docs/usage.md, docs-site/src/content/docs/reference/cli-reference.md, and README.md
• Issue: Flag exists in implementation but has zero user-facing documentation
• Implementation description: "Container runtime for the agent container. \"gvisor\" — OCI runtime via Docker Compose (translates to runsc). \"sbx\" — Docker sbx microVM with hypervisor isolation. Unknown values are passed through as raw Docker runtime names."
• Suggestion: Add to the Image Management section in both docs/usage.md and cli-reference.md. This is a significant capability (gVisor/sbx isolation) that operators would want to know about.

---

Issue 2 — --vertex-api-target and --vertex-api-base-path not documented

• Location: src/cli-options.ts (defined), absent from all docs
• Issue: Vertex AI target/path flags exist in implementation but are not in docs/usage.md, cli-reference.md, or README.md. All other provider *-api-target and *-api-base-path pairs (OpenAI, Anthropic, Gemini, Copilot) are documented.
• Expected: Vertex AI should be listed alongside Gemini in the API Proxy section of both doc files
• Suggestion: Add to the API Proxy section of docs/usage.md and the cli-reference.md options summary table.

---

Issue 3 — --openai-api-auth-header and --anthropic-api-auth-header not documented

• Location: src/cli-options.ts (defined), absent from all docs
• Issue: Custom authentication header override flags are not documented in either docs/usage.md or cli-reference.md. These enable non-standard auth schemes (e.g., Databricks, Azure OpenAI) so are likely useful to enterprise users.
• Implementation descriptions:
  • --openai-api-auth-header: "Custom auth header name for OpenAI requests (default: Authorization with ******"
  • --anthropic-api-auth-header: "Custom auth header name for Anthropic requests (default: x-api-key)"
• Suggestion: Add to the API Proxy flags section of both documentation files.

---

Issue 4 — --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses not documented

• Location: src/cli-options.ts (defined), absent from both docs/usage.md and cli-reference.md
• Issue: Four API proxy governance flags are entirely absent from user documentation. These control cost accounting and credential-failure circuit-breaking, which are important operational features.
• Implementation descriptions:
  • --max-model-multiplier: Per-model cost multipliers for effective token accounting
  • --max-model-multiplier-cap: Maximum allowed model cost multiplier (rejects requests over cap with HTTP 400)
  • --max-permission-denied: Maximum 401/403 upstream responses before proxy shuts down
  • --max-cache-misses: Maximum consecutive cache misses before stopping
• Suggestion: Add a new Rate Limiting & Budget Controls subsection to the API Proxy section of docs/usage.md, and add entries to the options summary table in cli-reference.md.

---

Issue 5 — AGENTS.md describes --dns-servers default as Google DNS, not auto-detected

• Location: AGENTS.md under DNS Configuration → Default: Google DNS (8.8.8.8,8.8.4.4)
• Issue: The actual behaviour (correctly described in docs/usage.md and cli-reference.md) is to auto-detect from host resolvers and fall back to Google DNS only if detection fails. AGENTS.md states Google DNS as the primary default, which is misleading for AI agents using that file.
• Current: "Default: Google DNS (8.8.8.8,8.8.4.4)"
• Expected: "Default: auto-detected from host resolvers; falls back to 8.8.8.8,8.8.4.4"
• Suggestion: Update the DNS Configuration section bullet in AGENTS.md (and identically in CLAUDE.md, which is a copy).

---

Issue 6 — AGENTS.md/CLAUDE.md references src/cli.ts as flag definition location

• Location: AGENTS.md first paragraph: "The system is orchestrated by src/cli.ts"; Custom instruction header mentions src/cli.ts as source of truth for flags
• Issue: Flag definitions were refactored into src/cli-options.ts. src/cli.ts is now a thin entry-point that imports from cli-options.ts. Any agent told to read src/cli.ts for flag definitions will find an empty 8-line file.
• Suggestion: Update references in AGENTS.md/CLAUDE.md to note that flag definitions live in src/cli-options.ts.

---

📋 Recommendations

🔴 High Priority

1. Document --max-model-multiplier, --max-model-multiplier-cap, --max-permission-denied, --max-cache-misses — These are cost-control and safety-circuit features that operators running production workloads need to know about. Missing docs means users cannot discover or configure these protections.

2. Document --container-runtime — gVisor (gvisor) and sbx microVM (sbx) isolation are major security features. Absence from docs means users default to the standard runtime even when stronger isolation is available.

🟡 Medium Priority

3. Document --vertex-api-target / --vertex-api-base-path — Every other provider target is documented; Vertex AI is the odd one out. Affects Google Cloud users using Vertex AI instead of the direct Gemini API.

4. Document --openai-api-auth-header / --anthropic-api-auth-header — Required for enterprise deployments using Azure OpenAI or Databricks model serving that use non-standard auth header names.

5. Fix AGENTS.md/CLAUDE.md DNS default description — Incorrect defaults in agent instruction files lead AI coding assistants to generate incorrect --dns-servers usage suggestions.

🟢 Low Priority

6. Update AGENTS.md/CLAUDE.md to reference src/cli-options.ts — Minor accuracy improvement for AI agents doing code investigation.

---

📁 Files Analyzed

File	Role	Flags Documented
src/cli-options.ts	Implementation (source of truth)	67 flags defined
docs/usage.md	User-facing usage guide	58 / 67 flags
docs-site/src/content/docs/reference/cli-reference.md	Detailed reference	58 / 67 flags
README.md	Overview / quick-start	Core flags only (by design)
AGENTS.md	AI agent instructions	Key flags mentioned
CLAUDE.md	AI agent instructions (copy)	Key flags mentioned

Report generated automatically from src/cli-options.ts by the CLI Flag Consistency Checker workflow on 2026-07-12.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by CLI Flag Consistency Checker · 65 AIC · ⊞ 5.3K · ◷

• expires on Jul 19, 2026, 11:41 AM UTC

[github-actions[bot]]

🔮 The ancient spirits stir, and the smoke test agent was here.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• awmgmcpg
• registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex
_{Add label ready-for-aw to run again}

[github-actions[bot]]

🔮 The ancient spirits stir across the firewall.
Smoke test agent was here, and the omens read PASS.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• awmgmcpg
• registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex
_{Add label ready-for-aw to run again}

[github-actions[bot]]

🔮 The ancient spirits stir, and the smoke-test agent has passed through this discussion.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• awmgmcpg
• registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex
_{Add label ready-for-aw to run again}