[CLI Flag Review] Weekly CLI Flag Consistency Report — 2026-06-29

[github-actions[bot]]

📊 Summary

Weekly automated check: src/cli-options.ts (64 flags) vs documentation files.

Metric	Count
Total flags in cli-options.ts	64
Flags fully covered (usage.md + cli-reference.md)	54
Flags with ≥1 gap	10
Flags missing from all user-facing docs	6

---

✅ Flag Coverage Matrix

Flag	usage.md	cli-reference.md	README.md	AGENTS.md	Status
--config	✅	✅	✅	❌	✅ OK
--allow-domains	✅	✅	✅	✅	✅ OK
--allow-domains-file	✅	✅	❌	❌	✅ OK
--ruleset-file	✅	✅	❌	❌	✅ OK
--block-domains	✅	✅	❌	❌	✅ OK
--block-domains-file	✅	✅	❌	❌	✅ OK
--ssl-bump	✅	✅	✅	❌	✅ OK
--allow-urls	✅	✅	✅	❌	✅ OK
--build-local	✅	✅	❌	✅	✅ OK
--agent-image	✅	✅	❌	❌	✅ OK
--image-registry	✅	✅	❌	✅	✅ OK
--image-tag	✅	✅	❌	✅	✅ OK
--skip-pull	✅	✅	❌	❌	✅ OK
--docker-host	✅	✅	❌	✅	✅ OK
--docker-host-path-prefix	✅	❌	❌	✅	⚠️ Missing cli-reference.md
--env	✅	✅	❌	❌	✅ OK
--env-all	✅	✅	❌	❌	✅ OK
--exclude-env	✅	✅	❌	❌	✅ OK
--env-file	✅	✅	❌	❌	✅ OK
--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	✅	❌	❌	❌	⚠️ Missing cli-reference.md
--topology-attach	✅	❌	❌	❌	⚠️ Missing cli-reference.md
--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 all docs
--anthropic-api-auth-header	❌	❌	❌	❌	🔴 Missing all docs
--gemini-api-target	✅	✅	❌	❌	✅ OK
--gemini-api-base-path	✅	✅	❌	❌	✅ OK
--anthropic-auto-cache	✅	❌	❌	❌	⚠️ Missing cli-reference.md
--anthropic-cache-tail-ttl	✅	❌	❌	❌	⚠️ Missing cli-reference.md
--rate-limit-rpm	✅	✅	❌	❌	✅ OK
--rate-limit-rph	✅	✅	❌	❌	✅ OK
--rate-limit-bytes-pm	✅	✅	❌	❌	✅ OK
--no-rate-limit	✅	✅	❌	❌	✅ OK
--max-model-multiplier	❌	❌	❌	❌	🔴 Missing all docs
--max-model-multiplier-cap	❌	❌	❌	❌	🔴 Missing all docs
--max-permission-denied	❌	❌	❌	❌	🔴 Missing all docs
--max-cache-misses	❌	❌	❌	❌	🔴 Missing all docs
--enable-token-steering	❌	✅	❌	❌	⚠️ Missing usage.md
--difc-proxy-host	✅	✅	❌	❌	✅ OK
--difc-proxy-ca-cert	✅	✅	❌	❌	✅ OK
--log-level	✅	✅	❌	✅	✅ OK
--keep-containers	✅	✅	❌	✅	✅ OK
--agent-timeout	✅	✅	✅	❌	✅ OK
--work-dir	✅	✅	❌	❌	✅ OK
--proxy-logs-dir	✅	✅	❌	❌	✅ OK
--audit-dir	✅	✅	✅	❌	✅ OK
--session-state-dir	✅	✅	❌	❌	✅ OK
--diagnostic-logs	✅	✅	❌	❌	✅ OK

README.md and AGENTS.md are intentionally selective — not expected to list every flag.

---

⚠️ Issues Found

🔴 High — Flags missing from ALL user-facing docs

Flag	Description	Requires
--openai-api-auth-header <name>	Custom auth header for OpenAI (default: Authorization Bearer)	--enable-api-proxy
--anthropic-api-auth-header <name>	Custom auth header for Anthropic (default: x-api-key)	--enable-api-proxy
--max-model-multiplier <model:N,...>	Per-model cost multipliers for token accounting (e.g. claude-opus-4-5-1m:10)	--enable-api-proxy
--max-model-multiplier-cap <n>	Rejects requests if model multiplier exceeds cap (HTTP 400)	--enable-api-proxy
--max-permission-denied <n>	Stops run after N upstream 401/403 responses (safety guard for bad credentials)	--enable-api-proxy
--max-cache-misses <n>	Stops run after N consecutive Anthropic cache misses	--enable-api-proxy

All six are undocumented API proxy flags in src/cli-options.ts. Add to both docs/usage.md and cli-reference.md.

🟡 Medium — Flags missing from cli-reference.md only

These are documented in docs/usage.md but absent from the docs-site reference:

• --docker-host-path-prefix <prefix> — ARC/DinD split-filesystem path prefix for bind mounts
• --network-isolation — Experimental iptables-free egress (no sudo required)
• --topology-attach <name> — Attach trusted containers under --network-isolation (repeatable)
• --anthropic-auto-cache — Auto-inject Anthropic cache breakpoints (~90% input cost savings)
• --anthropic-cache-tail-ttl <5m|1h> — TTL for rolling-tail cache breakpoint

🟡 Medium — Flag missing from docs/usage.md only

• --enable-token-steering — Has a full detail section in cli-reference.md but no entry in docs/usage.md.

🔵 Low — AGENTS.md/CLAUDE.md observations

1. Container count stale: Both files say "Three Container Components... one optional" but a 4th optional cli-proxy container is started when --difc-proxy-host is used.
2. --dns-servers default wording: States Default: Google DNS (8.8.8.8,8.8.4.4) — actual behavior is auto-detect from host resolvers, falling back to Google DNS. Both usage.md and cli-reference.md describe this correctly.

---

📋 Recommendations

High priority: Add the 6 undocumented API proxy flags to docs/usage.md and cli-reference.md.

Medium priority:

• Add 5 flags to cli-reference.md (already in usage.md): --docker-host-path-prefix, --network-isolation, --topology-attach, --anthropic-auto-cache, --anthropic-cache-tail-ttl
• Add --enable-token-steering to docs/usage.md

Low priority: Update AGENTS.md/CLAUDE.md container count and --dns-servers default description.

---

📁 Files Analyzed

File	Flags Mentioned
src/cli-options.ts (source of truth)	64
docs/usage.md	58
docs-site/.../cli-reference.md	53
README.md	~10 (by design)
AGENTS.md / CLAUDE.md	13 (by design)

Generated automatically · Run ID 28394132213

Generated by CLI Flag Consistency Checker · 147.7 AIC · ⊞ 6K · ◷

• expires on Jul 6, 2026, 6:42 PM UTC

[github-actions[bot]]

🔮 The ancient spirits stir over this smoke test.

A brief omen from the agent: the checks were run, the build held, and the firewall stands watch.

May the paths remain clear and the domains true.

Warning

Firewall blocked 1 domain

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

• registry.npmjs.org

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

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

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

🔮 The ancient spirits stir, and this smoke test agent has passed through the firewall’s veil. The run is observed, the paths are clear, and the oracle notes: all signs point toward safe passage.

Warning

Firewall blocked 1 domain

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

• registry.npmjs.org

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

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

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

🔮 The ancient spirits stir, and the smoke test agent has passed through this discussion. The run was observed, the omens read, and the firewall remains in balance.

Warning

Firewall blocked 1 domain

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

• registry.npmjs.org

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

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

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

🔮 The ancient spirits stir, and the smoke test agent has passed through the mirror of this discussion. The omens are clean, the build is sound, and the firewall holds.

Warning

Firewall blocked 1 domain

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

• registry.npmjs.org

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

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

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions[bot]]

🔮 The ancient spirits stir, and the smoke test agent passed through this discussion in peace. May the logs remain clear and the build remain green.

Warning

Firewall blocked 1 domain

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

• registry.npmjs.org

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

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

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex