[cli-consistency] CLI Consistency Issues - 2026-05-01

[github-actions]

Summary

Automated CLI consistency inspection found 8 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.

Breakdown by Severity

• High: 0 (No functional breakage found)
• Medium: 3 (Misleading/confusing text)
• Low: 5 (Minor wording/style issues)

Inspection Details

• Total Commands Inspected: 27
• Commands with Issues: 7
• Date: 2026-05-01
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency (-e, -r, -d, -j, -o, -v are used consistently)
• Example syntax correctness
• Subcommand structure (mcp, pr, secrets, project, completion)
• Global flags (--banner, -v, -h) applied uniformly

⚠️ Issues found:

• gh aw logs --after flag naming vs --start-date semantic conflict
• gh aw run unclear phrasing "added as actions"
• gh aw compile short description inconsistent with main help listing
• Minor grammatical/style issues in trial, new, logs

Detailed Findings

1. --after flag in gh aw logs has misleading semantics

Command Affected: gh aw logs
Priority: Medium
Type: Misleading flag name

Current Output (from ./gh-aw logs --help):

  gh aw logs --start-date -1w          # Download up to 10 runs from last week

  # Cache maintenance
  gh aw logs --after -1w                # Delete cached run folders older than 1 week

      --after string          (Cache eviction) Delete locally cached run folders older than
                              this cutoff date, before downloading. Use deltas like -1w or
                              -1mo, or an absolute date YYYY-MM-DD.
      --start-date string     Filter runs created after this date (YYYY-MM-DD or delta like
                              -1d, -1w, -1mo)

Issue: The --after flag and --start-date flag both accept the same -1w format, but with opposite semantics:

• --start-date -1w → "show runs from after 1 week ago" (newer than)
• --after -1w → "delete cache entries from before 1 week ago" (older than)

A user who reads --after -1w without the description could easily assume it filters downloads like --start-date does. Additionally, the examples section uses "# Cache maintenance" while the flag description says "(Cache eviction)" — inconsistent terminology for the same concept.

Suggested Fix: Add a clearer warning in the examples section, or rename the flag to --evict-before / --purge-cache-before to make the direction unambiguous. Standardize terminology to either "cache eviction" or "cache maintenance" throughout.

---

2. gh aw run uses unclear phrasing "added as actions"

Command Affected: gh aw run
Priority: Medium
Type: Unclear/confusing wording

Current Output (from ./gh-aw run --help):

This command accepts one or more workflow IDs.
The workflows must have been added as actions and compiled.

This command only works with workflows that have workflow_dispatch triggers.

Issue: "added as actions" is non-standard terminology. The GitHub CLI extension ecosystem doesn't normally refer to workflows as "actions." A user unfamiliar with the tool's concepts won't know what "added as actions" means. The intended meaning appears to be: "added to .github/workflows (via gh aw add) and compiled (via gh aw compile)."

Suggested Fix: Change to: "The workflows must have been added to .github/workflows and compiled."

---

3. gh aw compile short description inconsistent with main help

Command Affected: gh aw compile
Priority: Medium
Type: Inconsistent terminology

Current Output:

• Main help listing: compile Compile agentic workflow Markdown files into GitHub Actions YAML
• gh aw compile --help first line: Compile one or more agentic workflows to YAML workflows.

Issue: "to YAML workflows" is redundant (a workflow is already a workflow) and inconsistent with the cleaner "into GitHub Actions YAML" phrasing in the main help listing.

Suggested Fix: Change the compile long description opening to: Compile one or more agentic workflow Markdown files into GitHub Actions YAML.

---

4. gh aw trial missing article before "workflow_dispatch trigger"

Command Affected: gh aw trial
Priority: Low
Type: Grammar

Current Output (from ./gh-aw trial --help):

All workflows must support workflow_dispatch trigger to be used in trial mode.

Issue: Missing article "the" before "workflow_dispatch trigger".

Suggested Fix: Change to: All workflows must support the workflow_dispatch trigger to be used in trial mode.

---

5. gh aw new missing article before "--interactive flag"

Command Affected: gh aw new
Priority: Low
Type: Grammar

Current Output (from ./gh-aw new --help):

When called without a workflow name (or with --interactive flag), launches an interactive wizard

Issue: Missing article "the" before "--interactive flag".

Suggested Fix: Change to: When called without a workflow name (or with the --interactive flag), launches an interactive wizard

---

6. gh aw logs --train exposes internal library name in help text

Command Affected: gh aw logs
Priority: Low
Type: Leaking implementation details

Current Output (from ./gh-aw logs --help):

      --train                 Analyze log patterns across downloaded runs and save pattern
                              weights to drain3_weights.json in the output directory

Issue: drain3_weights.json is named after drain3, a third-party log parsing library. Exposing internal library names in user-facing help text couples the interface to the implementation. If the library changes, the filename in the help text would become stale.

Suggested Fix: Use a generic name: save pattern weights to log-weights.json in the output directory, or at minimum weights.json.

---

7. gh aw logs terminology inconsistency: "cache maintenance" vs "cache eviction"

Command Affected: gh aw logs
Priority: Low
Type: Terminology inconsistency

Current Output (from ./gh-aw logs --help):

  # Cache maintenance
  gh aw logs --after -1w                # Delete cached run folders older than 1 week

      --after string          (Cache eviction) Delete locally cached run folders...

Issue: The examples section header uses "Cache maintenance" while the flag description uses "(Cache eviction)". These should be consistent.

Suggested Fix: Use a single term consistently, e.g., "Cache eviction" in both places.

---

8. gh aw run --approve flag placement is surprising

Command Affected: gh aw run
Priority: Low
Type: Missing context in flag description

Current Output (from ./gh-aw run --help):

      --approve   Approve all safe update changes. When strict mode is active (the default),
                  the compiler emits warnings for new restricted secrets or unapproved action
                  additions/removals not present in the existing gh-aw-manifest. Use this flag
                  to approve and skip safe update enforcement

Issue: The --approve flag is a compilation concern, yet it appears in run without explanation of why it's needed there. A user running gh aw run would not expect to see compiler-related flags. The description mentions "the compiler emits warnings" which implies run invokes compilation, but this is not stated anywhere in the command description.

Suggested Fix: Add a note in the run command description that explains it may invoke compilation internally (e.g., "If changes are detected, the workflow may be recompiled before running."), or add a brief note to the --approve flag description like: "Available here because run may invoke compilation when changes are detected."

Generated by CLI Consistency Checker · ● 788.5K · ◷

• expires on May 3, 2026, 1:43 PM UTC

[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 · ● 28K · ◷