[CLI Flag Review] CLI Flag Consistency Report — 2026-06-01

[github-actions[bot]]

📊 Summary

Item	Count
Total flags in src/cli-options.ts	59
Flags with documentation gaps	4
Inconsistencies found	7
Files analyzed	6

Overall the documentation is well-maintained. Four flags are undocumented and there are minor description and short-form omissions.

---

✅ Flags Coverage (Condensed)

55 of 59 flags are consistently documented. The 4 exceptions:

Flag	usage.md	cli-reference.md	Status
--openai-api-auth-header	❌	❌	❌ Undocumented
--anthropic-api-auth-header	❌	❌	❌ Undocumented
--max-model-multiplier	❌	❌	❌ Undocumented
--docker-host-path-prefix	✅	❌	⚠️ Missing from cli-reference

Short forms also missing from cli-reference.md table: -d (--allow-domains), -b (--build-local), -k (--keep-containers) — the same table shows -e and -v correctly.

---

⚠️ Issues Found

1. --openai-api-auth-header and --anthropic-api-auth-header — Undocumented

Both flags are defined in src/cli-options.ts but absent from docs/usage.md and cli-reference.md. They enable custom authentication schemes (Azure OpenAI, Databricks, etc.) — high-value flags with zero discoverability.

Fix: Add entries to the API Proxy section of both files:

• --openai-api-auth-header <name> — Custom auth header for OpenAI requests (default: Authorization with Bearer prefix)
• --anthropic-api-auth-header <name> — Custom auth header for Anthropic requests (default: x-api-key)

2. --max-model-multiplier — Undocumented

Defined in src/cli-options.ts (lines 334–340) but absent from all user-facing docs. This is a meaningful cost-control feature for rate limiting by effective token spend.

Fix: Add to the Rate Limiting section in both usage.md and cli-reference.md. Format: comma-separated model:multiplier pairs, e.g. claude-opus-4-5-1m:10,claude-opus-4-5-200k:2.5. Requires --enable-api-proxy.

3. --docker-host-path-prefix — Missing from cli-reference.md

Present in usage.md and AGENTS.md but absent from cli-reference.md (no table row, no detail section). --docker-host is documented at table row 39; --docker-host-path-prefix is not.

Fix: Add a table row alongside --docker-host and a ### --docker-host-path-prefix detail section near the ARC/DinD content.

4. Short forms -d, -b, -k missing from cli-reference.md table

Three flags with short aliases show only their long form in the options summary table:

Implementation	Table shows
-d, --allow-domains	--allow-domains
-b, --build-local	--build-local
-k, --keep-containers	--keep-containers

Compare: -e, --env and -v, --mount are shown correctly in the same table.

Fix: Update the three table cells to include the short form.

5. --enable-api-proxy description stale in src/cli-options.ts

awf --help shows: "Supports OpenAI (Codex) and Anthropic (Claude) APIs"

The proxy also supports Copilot and Gemini (both have dedicated flags). The --help output is misleading.

Fix: Change to: "Supports OpenAI, Anthropic, Copilot, and Gemini APIs."

6. --dns-servers default inaccurate in AGENTS.md

AGENTS.md states: "Default: Google DNS (8.8.8.8,8.8.4.4)"

The implementation auto-detects DNS from the host and only falls back to Google DNS. cli-reference.md correctly says "Auto-detected from host, falls back to 8.8.8.8,8.8.4.4".

Since AGENTS.md is read by AI coding agents, a wrong default can propagate into generated configs.

Fix: Update to: "Default: Auto-detected from host; falls back to 8.8.8.8,8.8.4.4".

---

📋 Prioritized Recommendations

High — undiscoverable features for users:

1. Document --openai-api-auth-header and --anthropic-api-auth-header in usage.md + cli-reference.md
2. Document --max-model-multiplier in the Rate Limiting section of both files

Medium — reference doc completeness:
3. Add --docker-host-path-prefix to cli-reference.md table + detail section
4. Restore -d, -b, -k short forms in cli-reference.md table
5. Update --enable-api-proxy help text in src/cli-options.ts

Low — agent instruction accuracy:
6. Fix --dns-servers default description in AGENTS.md

---

📁 Files Analyzed

File	Lines
src/cli-options.ts	401 (59 flags)
docs/usage.md	1,207
docs-site/src/content/docs/reference/cli-reference.md	1,390
README.md	103
AGENTS.md	397
CLAUDE.md	present

Generated by CLI Flag Consistency Checker · sonnet46 2M · ◷

• expires on Jun 8, 2026, 7:38 PM UTC

[github-actions[bot]]

🔮 The ancient spirits stir, and the smoke test agent has crossed the veil unscathed. The oracle foresees a passing build, a true title, and a quiet filesystem.

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; the smoke test agent has passed through this discussion and left its mark.

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