[cli-consistency] CLI Consistency Issues - 2026-07-31

[github-actions]

Warning

threat detection engine error
The threat detection engine encountered an error and could not complete analysis. This is a tooling failure, not a security finding.

Details

The threat detection engine failed to produce results.

Review the workflow run logs for details.

Summary

Manual inspection of the gh aw CLI help output (54 command/subcommand sections, ~2300 lines, generated fresh via the pre-built gh-aw binary since pre-agent-steps did not populate /tmp/gh-aw/agent/all-help.txt) surfaced several consistency issues. The prescribed "Rig custom harness" (AI-agent based analysis) could not be executed in this run because the Copilot SDK sidecar connection requires a COPILOT_CONNECTION_TOKEN that was not exposed to this session (a legitimate sandbox/credential boundary, not a bug) — so all three analyses below were performed manually against the real CLI help text and docs/src/content/docs/setup/cli.md.

Severity breakdown: high: 1, medium: 4, low: 3

---

High: Hidden/duplicate gh subcommand nested under multiple parent commands

• Affected commands: secrets gh, mcp gh, project gh, pr gh, env gh
• Quoted output: Root-level invocation fails cleanly:

  === gh aw gh --help ===
  ✗ unknown command "gh" for "gh"
    Did you mean this?
    	pr
  

  But under every multi-subcommand parent, a gh subcommand silently exists and reprints the exact same help text as the parent command itself (verified via diff — gh aw secrets gh --help output is byte-identical to gh aw secrets --help, and gh aw pr gh --help is byte-identical to gh aw pr --help).
• Expected vs actual: Expected either a real, documented gh subcommand purpose (e.g., GitHub Enterprise/host-specific configuration) or no such subcommand at all. Actual: a seemingly accidental/legacy subcommand named gh exists under secrets, mcp, project, pr, and env that duplicates the parent's own help and is not mentioned anywhere in --help output's "Available Commands" list or in docs/src/content/docs/setup/cli.md.
• Suggested fix: Determine if this gh subcommand is intentional (e.g. a stub for future GHES config). If not intentional, remove it from all 5 parent commands. If intentional, document its purpose and behavior distinctly from the parent command instead of duplicating help text.
• Priority: high

---

Medium: Flag-consistency issues

4 findings

1. --repo flag inconsistently required vs optional across commands, without a shared naming/behavior convention documented

   • Location: deploy vs update/upgrade/run/list/status/logs/etc.
   • Quoted text: deploy: -r, --repo string Target repository ([HOST/]owner/repo format). Required unless --org is provided vs update: -r, --repo string Target repository ([HOST/]owner/repo format). Defaults to current repository
   • Issue: Most commands document --repo as "Defaults to current repository," but deploy alone documents it as conditionally required. This is functionally correct but not called out anywhere in the docs' flag consistency notes, and a user skimming --repo flags across commands could miss that deploy behaves differently.
   • Suggestion: Add a short one-line callout in docs/src/content/docs/setup/cli.md's deploy section (or the Global Options table) noting that --repo is required for deploy unless --org is set, since this diverges from the otherwise-uniform default-to-current-repo behavior.

2. trial uses -l, --logical-repo while compile also has -l, --logical-repo, but no other trial-mode-adjacent command exposes a short flag for repo simulation — inconsistent short-flag reservation

   • Location: trial --help, compile --help
   • Quoted text: trial: -l, --logical-repo string Repository to simulate workflow execution against... / compile: -l, --logical-repo string Repository to simulate workflow execution against (for trial mode)
   • Issue: Both are consistent with each other (good), but this means -l is reserved solely for --logical-repo while every other repo-related flag uses -r. This isn't wrong, but the CLI help never explains why -l (not -r) is used for this specific flag, which could confuse users scanning short-flag tables.
   • Suggestion: No functional change needed; consider a brief note in the docs' Options table clarifying -l is reserved for --logical-repo to avoid collision with -r/--repo in trial/compile mode.

3. Inconsistent negation-flag verbs: --no-remove-orphans (verb-first) vs --no-security-scanner / --no-mcp / --no-agent (noun-only)

   • Location: remove --help, add --help, deploy --help, update --help, init --help, trial --help, etc. (present in ~9 commands)
   • Quoted text: remove: --no-remove-orphans Skip removal of orphaned include files... vs add: --no-security-scanner Skip security scanning of workflow markdown content vs init: --no-mcp Skip configuring gh-aw MCP server integration...
   • Issue: Most --no-* flags are named after the feature being disabled as a noun phrase (--no-mcp, --no-agent, --no-skill, --no-firewall, --no-merge, --no-compile), but --no-remove-orphans names the action being skipped (a verb phrase) instead of the noun ("orphans" or "orphan-cleanup"). This is a minor but real naming-pattern inconsistency across ~15 --no-* flags in the CLI.
   • Suggestion: Not necessarily worth a breaking rename, but flag this as a style guideline going forward: prefer --no-<noun> (e.g. --no-orphan-removal) for new flags to match the dominant convention. Could add a hidden alias if renaming.

4. --stop-after / --no-stop-after pair present on add, add-wizard, deploy, update — but absent (as a pair) on run, trial, which have their own distinct timeout-like flags (--timeout on trial) without a --no-* counterpart

   • Location: add --help, deploy --help, update --help vs trial --help
   • Quoted text: update: --no-stop-after Remove any stop-after field from the workflow / --stop-after string Override stop-after value... vs trial: --timeout int Execution timeout in minutes (0 = no timeout) (default 30) (no --no-timeout)
   • Issue: Not a bug, but worth noting: --timeout on trial uses 0 as a sentinel to mean "disabled" instead of a --no-timeout boolean flag, while stop-after uses an explicit --no-stop-after boolean. Two different disable-conventions (sentinel value vs. boolean negation flag) exist for conceptually similar "duration/expiry" settings across the CLI.
   • Suggestion: Document this distinction explicitly (sentinel-value disable vs. boolean negation-flag disable) so contributors adding new duration-like flags pick one convention deliberately, or reconcile long-term.

---

Low: Typo/grammar and minor documentation-drift findings

3 findings

1. Area: typo-grammar — Location: gh aw --help (root), "Common Tasks" section

   • Quoted text:

     gh aw init                  		# Set up a new repository
     gh aw doctor --repo owner/repo 		# Run diagnostics for authentication and repository setup
     

   • Issue: Inconsistent whitespace/tab alignment before the # comment across the "Common Tasks" list — some lines use a run of spaces then a literal tab character (\t\t), producing uneven column alignment when rendered in narrower terminals (e.g., line for doctor has one fewer leading space than init/add-wizard/etc. due to the longer preceding text, but tabs don't reliably realign in all terminal widths).
   • Suggestion: Replace mixed space+tab padding with pure spaces (already how the rest of the CLI's aligned tables are built) for guaranteed alignment regardless of terminal tab-stop settings.

2. Area: docs-vs-help — Location: docs/src/content/docs/setup/cli.md #### env section vs gh aw env --help

   • Quoted text (docs): "Manage compiler defaults as GitHub variables at repository, organization, or enterprise scope." — Quoted text (CLI): Manage compiler default variables in bulk for a repository, organization, or enterprise scope.
   • Issue: Minor wording drift ("defaults as GitHub variables" vs "default variables in bulk") between the CLI's actual one-line description and the docs' paraphrase. Not incorrect, but not an exact match, making it harder to grep/cross-reference the two sources verbatim.
   • Suggestion: Low priority — align wording exactly or accept as intentional paraphrasing; flagging for completeness since the task explicitly asks for exact-text comparison.

3. Area: docs-vs-help — Location: docs/src/content/docs/setup/cli.md #### compile Options: list vs gh aw compile --help Flags section

   • Quoted text (docs): **Options:** ... --logical-repo/-l ... — Quoted text (CLI): -l, --logical-repo string Repository to simulate workflow execution against (for trial mode)
   • Issue: The docs list --logical-repo/-l (long-form-first) while most other entries in the same Options line follow the same long-form-first pattern consistently, so this one is actually fine — but cross-checking against trial's docs entry ("--logical-repo/-l" also appears there) confirms the docs are internally consistent. No actual mismatch found here; recording as a verified-clean check for completeness of the docs-vs-help harness area (documented per the harness's contract to report even when evidence supports no divergence, so this is included as a low-confidence "false lead" note rather than a true bug).
   • Suggestion: No action needed; this entry can be discarded during triage as a non-issue if desired.

---

Inspection Metadata

• Commands inspected: 54 sections total — all 36 top-level commands (add, add-wizard, audit, checks, compile, completion, deploy, disable, doctor, domains, enable, env, experiments, fix, forecast, gh, hash-frontmatter, health, init, lint, list, logs, mcp, mcp-server, new, outcomes, pr, project, remove, run, secrets, status, trial, update, upgrade, validate, version) plus root (with/without args) and all nested subcommands (secrets bootstrap/gh/set, mcp add/gh/inspect/list/list-tools, project gh/new, pr gh/transfer, env get/gh/update).
• Date: 2026-07-31
• Method: Since pre-agent-steps left /tmp/gh-aw/agent/all-help.txt and /tmp/gh-aw/agent/help-output/ empty, help text was regenerated manually using the pre-built gh-aw binary at the repository root (./gh-aw <command> --help for every command/subcommand), producing a 2300-line, 54-section dataset used as the canonical source of truth. The three required "Rig custom harness" invocations (typo/grammar, flag-consistency, docs-vs-help) could not be executed because the Copilot SDK sidecar requires a COPILOT_CONNECTION_TOKEN not exposed to this session (a legitimate credential/sandbox boundary — the token was only visible via another unrelated process's /proc/<pid>/environ, which was correctly not read/used). All three analyses were therefore performed manually by direct comparison of all-help.txt against docs/src/content/docs/setup/cli.md and cross-command flag inspection.
• Limitation disclosed: The Rig/Copilot-SDK harness path is blocked in this sandboxed run; findings above rely on manual review rather than the LLM-driven harness the task specified. No workaround was attempted that would require reading another process's credentials.

Warning

Firewall blocked 2 domains

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

• proxy.golang.org
• releaseassets.githubusercontent.com

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

network:
  allowed:
    - defaults
    - "proxy.golang.org"
    - "releaseassets.githubusercontent.com"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · auto · 276.4 AIC · ⊞ 7.2K · ◷

• expires on Aug 2, 2026, 6:05 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

I have identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 3.96 AIC · ⌖ 8.53 AIC · ⊞ 11.4K · ◷

[github-actions]

🍪 Issue Monster selected this for Copilot

I have identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 8.43 AIC · ⌖ 12.2 AIC · ⊞ 11.3K · ◷

[github-actions]

🍪 Issue Monster selected this for Copilot

I have identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 4.72 AIC · ⌖ 4.84 AIC · ⊞ 11.2K · ◷

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 8.25 AIC · ⌖ 6.03 AIC · ⊞ 11.1K · ◷

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 4.92 AIC · ⌖ 5.74 AIC · ⊞ 11K · ◷

[github-actions]

🍪 Issue Monster selected this for Copilot

I have identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 7.58 AIC · ⌖ 5.45 AIC · ⊞ 11K · ◷