[CLI Flag Review] Weekly CLI Flag Consistency Report — 2026-03-04

[github-actions[bot]]

📊 Summary

Metric	Count
Total flags in implementation (src/cli.ts)	29 main options + 9 subcommand options = 38
Flags missing from cli-reference.md	6
Flags missing from docs/usage.md (detailed section)	6
Flags missing from all primary docs	5
Default value discrepancies	1
Total inconsistencies	7

---

✅ Flags Status

Main Command Options

Flag	cli.ts	usage.md	cli-reference.md	README.md	Status
--allow-domains	✅	✅	✅	✅	✅ OK
--allow-domains-file	✅	✅	✅	❌	⚠️ Missing README
--block-domains	✅	✅	✅	❌	⚠️ Missing README
--block-domains-file	✅	✅	✅	❌	⚠️ Minor
--log-level	✅	✅	✅	❌	⚠️ Minor
--keep-containers	✅	✅	✅	❌	⚠️ Minor
--tty	✅	✅	✅	❌	⚠️ Minor
--work-dir	✅	✅	✅	❌	⚠️ Minor
--build-local	✅	✅	✅	✅	✅ OK
--agent-image	✅	✅	✅	❌	⚠️ Minor
--image-registry	✅	✅	✅	❌	⚠️ Minor
--image-tag	✅	✅	✅	❌	⚠️ Minor
--skip-pull	✅	✅	✅	❌	⚠️ Minor
-e, --env	✅	✅	✅	❌	⚠️ Minor
--env-all	✅	✅	✅	❌	⚠️ Minor
-v, --mount	✅	✅	✅	❌	⚠️ Minor
--container-workdir	✅	✅	✅	❌	⚠️ Minor
--dns-servers	✅	✅	✅	❌	⚠️ Minor
--proxy-logs-dir	✅	✅	✅	❌	⚠️ Minor
--enable-host-access	✅	✅	✅	❌	⚠️ Minor
--allow-host-ports	✅	✅	⚠️ Wrong default	❌	⚠️ Default mismatch
--ssl-bump	✅	✅	✅	❌	⚠️ Minor
--allow-urls	✅	✅	✅	❌	⚠️ Minor
--enable-api-proxy	✅	⚠️ Synopsis only	❌ Missing	❌	🔴 Missing docs
--copilot-api-target	✅	❌ Missing	❌ Missing	❌	🔴 Missing docs
--rate-limit-rpm	✅	❌ Missing	❌ Missing	❌	🔴 Missing docs
--rate-limit-rph	✅	❌ Missing	❌ Missing	❌	🔴 Missing docs
--rate-limit-bytes-pm	✅	❌ Missing	❌ Missing	❌	🔴 Missing docs
--no-rate-limit	✅	❌ Missing	❌ Missing	❌	🔴 Missing docs

awf logs Subcommand Options

Flag	cli.ts	usage.md	cli-reference.md	Status
-f, --follow	✅	✅	✅	✅ OK
--format	✅	✅	✅	✅ OK
--source	✅	✅	✅	✅ OK
--list	✅	✅	✅	✅ OK
--with-pid	✅	✅	✅	✅ OK

awf logs stats Subcommand Options

Flag	cli.ts	usage.md	cli-reference.md	Status
--format	✅	✅	✅	✅ OK
--source	✅	✅	✅	✅ OK

awf logs summary Subcommand Options

Flag	cli.ts	usage.md	cli-reference.md	Status
--format	✅	✅	✅	✅ OK
--source	✅	✅	✅	✅ OK

---

⚠️ Issues Found

🔴 Issue 1: --enable-api-proxy missing from cli-reference.md

• Location: docs-site/src/content/docs/reference/cli-reference.md
• Issue: The --enable-api-proxy flag (and all related API proxy flags) are completely absent from the CLI reference document.
• Expected: An entry in the Options Summary table and a detailed ### --enable-api-proxy section with description, examples, and links to docs/api-proxy-sidecar.md.
• Current: The flag does not appear anywhere in cli-reference.md (confirmed with grep returning 0 matches).
• Suggestion: Add --enable-api-proxy, --copilot-api-target, and all --rate-limit-* flags to the Options Summary table, and add detailed sections in the Options Details area.

---

🔴 Issue 2: --copilot-api-target undocumented everywhere

• Location: docs/usage.md, docs-site/src/content/docs/reference/cli-reference.md, README.md, docs/api-proxy-sidecar.md, AGENTS.md, CLAUDE.md
• Issue: --copilot-api-target (host) is a user-facing CLI flag that overrides the Copilot API target hostname. It's implemented in src/cli.ts (line ~800) with the description "Defaults to api.githubcopilot.com. Useful for GHES deployments." — but appears in no documentation file.
• Expected: Documentation in at least docs/usage.md and docs-site/src/content/docs/reference/cli-reference.md, with a note in docs/api-proxy-sidecar.md since it only applies when --enable-api-proxy is used.
• Current: Zero matches across all documentation files. AGENTS.md does mention COPILOT_API_TARGET env var but not the corresponding CLI flag.
• Suggestion: Add to docs/api-proxy-sidecar.md as it is scoped to that feature, and list in the main CLI reference.

---

🔴 Issue 3: Rate-limiting flags (--rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm, --no-rate-limit) undocumented everywhere

• Location: docs/usage.md, docs-site/src/content/docs/reference/cli-reference.md, README.md, docs/api-proxy-sidecar.md
• Issue: All four rate-limiting CLI flags are implemented in src/cli.ts (lines ~800–820) but appear in no documentation file whatsoever.
• Expected: Documentation in docs/api-proxy-sidecar.md (as they require --enable-api-proxy) and in the CLI reference. The implementation note says the defaults when rate limiting is enabled are: rpm=600, rph=10000, bytesPm=52428800 (50MB) — none of this is documented.
• Current: Zero matches across all documentation files.
• Suggestion:
  1. Add a "Rate Limiting" section to docs/api-proxy-sidecar.md covering all four flags and their defaults.
  2. Add entries to the Options Summary table in cli-reference.md.
  3. Add to the synopsis block in docs/usage.md.

---

⚠️ Issue 4: --allow-host-ports incorrect default in cli-reference.md

• Location: docs-site/src/content/docs/reference/cli-reference.md, line 43
• Issue: The Options Summary table shows the default for --allow-host-ports as 80,443. However, in src/cli.ts, this option has no default value (the commander option is not given a default argument). docs/usage.md correctly documents: "When --enable-host-access is enabled without --allow-host-ports, all ports on host.docker.internal are currently allowed."
• Expected: The default column in cli-reference.md should read — (no default) with a note that all ports are allowed when omitted (current behavior, planned to change to 80,443 in a future version).
• Current: | --allow-host-ports (ports) | string | 80,443 | ... — this is incorrect.
• Suggestion: Change the default column to — and add a note: "When omitted, all ports are currently allowed (will default to 80,443 in a future version)."

---

⚠️ Issue 5: --enable-api-proxy has no dedicated section in docs/usage.md

• Location: docs/usage.md
• Issue: --enable-api-proxy appears only in the help synopsis block (line 63) but has no dedicated ### --enable-api-proxy section with description, examples, or cross-references — unlike every other flag.
• Expected: A section explaining what the API proxy does, what env vars it uses, and a link to docs/api-proxy-sidecar.md for full details.
• Current: Only the one-line synopsis entry.
• Suggestion: Add a brief ### --enable-api-proxy section pointing to docs/api-proxy-sidecar.md for complete documentation.

---

📋 Recommendations

🔴 High Priority

1. Document the 5 undocumented flags (--copilot-api-target, --rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm, --no-rate-limit):

   • Add a Rate Limiting section to docs/api-proxy-sidecar.md covering all rate-limit flags including their defaults (rpm=600, rph=10000, bytesPm=50MB) and the --no-rate-limit override.
   • Add --copilot-api-target to docs/api-proxy-sidecar.md with a GHES usage example.
   • Add all 6 API proxy-related flags to the Options Summary table in cli-reference.md.

2. Fix --enable-api-proxy in cli-reference.md — add entry to summary table and a detailed section.

⚠️ Medium Priority

3. Fix --allow-host-ports default value in cli-reference.md (line 43) — change 80,443 to — with a note about current behavior.

4. Add --enable-api-proxy section to docs/usage.md (even a brief one with a pointer to docs/api-proxy-sidecar.md).

📝 Low Priority

5. README coverage — Most flags are not listed in README, but this is intentional (README provides only a quick start). No action needed unless FLAGS table is desired there.

---

📁 Files Analyzed

File	Role	Status
src/cli.ts	Implementation (source of truth)	✅ Analyzed
docs/usage.md	Primary usage documentation	✅ Analyzed
docs-site/src/content/docs/reference/cli-reference.md	CLI reference (docsite)	✅ Analyzed
README.md	Quick start overview	✅ Analyzed
AGENTS.md	Agent instructions	✅ Analyzed
CLAUDE.md	Agent instructions	✅ Analyzed
docs/api-proxy-sidecar.md	API proxy feature docs	✅ Analyzed

---

Note: This report was generated automatically by analyzing src/cli.ts against all documentation files. The analysis was run on 2026-03-04. All line numbers reference the current main branch.

AI generated by CLI Flag Consistency Checker

• expires on Mar 11, 2026, 2:15 PM UTC