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

[github-actions]

Summary

Comprehensive CLI consistency inspection performed on 2026-07-10 across all gh aw commands.

Commands inspected: 25 top-level commands + subcommands
Total issues found: 25
Severity breakdown: 1 high · 7 medium · 17 low

---

Severity Breakdown

Severity	Count
🔴 High	1
🟡 Medium	7
🟢 Low	17

---

1. Grammar & Style Issues

7 issues (click to expand)

1.1 --fail-fast example comment incomplete — gh aw validate (low)

Quoted CLI output: gh aw validate --fail-fast # Stop at the first error
Expected: # Stop at the first validation error (matches the flag description)
Suggested fix: Update example comment to add the word "validation".

---

1.2 Missing blank line before "The workflow-id" paragraph — gh aw logs (low)

Quoted CLI output:

- summary.json: Complete metrics and run data for all downloaded runs
The workflow-id is the basename of the Markdown file without the .md extension.

Expected: A blank line between the artifact list and the The workflow-id is... paragraph.
Suggested fix: Add a blank line separator.

---

1.3 workflow(s) informal pluralization — gh aw trial (low)

Quoted CLI output: ...installs the specified workflow(s) from their source repositories...
Expected: ...installs the specified workflows from their source repositories...
Suggested fix: Remove parenthetical (s) — all other commands use the plain plural.

---

1.4 Floating "Unlike upgrade" sentence — gh aw compile (medium)

Quoted CLI output:

Unlike 'upgrade', compilation only applies codemods when you opt in with --fix.

  --action-mode <mode>

Expected: This sentence should appear in the opening description paragraph, not floating between unrelated sections.
Suggested fix: Move to opening description or add a Note: prefix.

---

1.5 "Flag behavior" bullets have lowercase openers — gh aw upgrade (low)

Quoted CLI output:

Flag behavior:
- upgrade runs codemods, action version updates, and workflow compilation by default; use --no-fix to skip all three steps
- --no-actions and --no-compile are only applied when --no-fix is not set

Suggested fix: Capitalize bullet openers and use complete sentences.

---

1.6 gh aw lint examples have no inline comments (low)

Quoted CLI output:

Examples:
  gh aw lint
  gh aw lint .github/workflows/foo.lock.yml
  gh aw lint --dir .github/workflows
  gh aw lint --shellcheck --pyflakes

Suggested fix: Add inline # comment descriptions to all example lines.

---

1.7 gh aw fix numbered steps missing terminal periods (low)

Quoted CLI output:

  4. Write updated files back to disk
  5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists

Suggested fix: Add periods consistently to all numbered steps.

---

2. Flag Naming & Description Inconsistencies

5 issues (click to expand)

2.1 --repo flag uses different phrasing on gh aw deploy (medium)

Quoted CLI output: -r, --repo string Target repository in [HOST/]owner/repo format (required unless --org is provided)
All other commands: Target repository ([HOST/]owner/repo format). Defaults to current repository
Issues: Different bracket style, missing trailing period.
Suggested fix: Target repository ([HOST/]owner/repo format). Required unless --org is provided

---

2.2 --no-security-scanner uses "Disable" while all other --no-* flags use "Skip" (low)

Affected commands: add, add-wizard, deploy, update, trial
Quoted CLI output: --no-security-scanner Disable security scanning of workflow markdown content
Suggested fix: Change Disable to Skip.

---

2.3 --dry-run descriptions use different verbs across commands (low)

gh aw run: Validate workflow without actually triggering execution on GitHub Actions
gh aw trial: Preview trial execution without applying any changes
Suggested fix: Standardize to one verb.

---

2.4 --no-compile description inconsistency between update and upgrade (low)

gh aw update: Missing ; ignored when --no-fix is set qualifier (which correctly appears in upgrade).

---

2.5 --last flag description omits -c short alias (low)

Quoted CLI output: --last int Alias for --count: number of recent runs to download
Docs say: "alias for --count/-c"
Suggested fix: Alias for --count/-c: number of recent runs to download

---

3. Command Description Gaps

5 issues (click to expand)

3.1 🔴 gh aw experiments documented in cli.md but absent from CLI (HIGH)

CLI output: The word "experiments" appears 0 times in CLI help output.
Docs (cli.md):

#### `experiments`
Inspect experiment state tracked in `experiments/*` branches.
gh aw experiments                          # List experiment workflow branches
gh aw experiments list --json             # List all experiments in JSON format
gh aw experiments analyze my-workflow     # Analyze one experiment workflow

Suggested fix: Either register the command in CLI help, or remove it from the public documentation.

---

3.2 gh aw upgrade opening description is vague (medium)

Quoted CLI output: Upgrade the repository to the latest version of agentic workflows.
Issue: Undistinguishable from gh aw update.
Suggested fix: Upgrade repository agent files, apply codemods, and recompile all workflows.

---

3.3 gh aw add one-line description omits local files and URL sources (medium)

Quoted CLI output: Add one or more agentic workflows from repositories to .github/workflows.
Suggested fix: Add one or more agentic workflows from repositories, URLs, or local files to .github/workflows.

---

3.4 gh aw env get / gh aw env update have no standalone help sections (medium)

Issue: Only the parent gh aw env section exists. Subcommand flags are undiscoverable.
Suggested fix: Ensure subcommands produce full --help output.

---

3.5 gh aw secrets set / gh aw secrets bootstrap have no standalone help sections (medium)

Issue: Only the parent gh aw secrets section exists. Flags like --value, --value-from-env, --non-interactive are undiscoverable from --help.
Suggested fix: Ensure subcommands produce full --help output.

---

4. Docs vs CLI Mismatches

4 issues (click to expand)

4.1 cli.md run examples omit --dry-run (low)

Suggested fix: Add gh aw run workflow --dry-run # Validate without actually running

---

4.2 cli.md run description says "Displays workflow URL for tracking" — not in CLI (low)

Docs text: Execute workflows immediately in GitHub Actions. Displays workflow URL for tracking.
Suggested fix: Add this sentence to CLI help, or remove from docs description.

---

4.3 --non-interactive documented for secrets bootstrap but absent from help (medium)

Docs: **Options:** --engine, --non-interactive, --repo
Suggested fix: Add full help section for gh aw secrets bootstrap.

---

4.4 Example workflow name inconsistency: daily-planner vs daily-plan (low)

gh aw forecast examples: Use daily-planner
gh aw trial / gh aw compile examples: Use daily-plan
Suggested fix: Standardize on daily-plan.

---

5. Example Accuracy Issues

4 issues (click to expand)

5.1 --start-date comments inconsistent — gh aw logs (medium)

Quoted CLI output:

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

Issue: Identical flags but one says "up to 10 runs" and the other "all runs".
Suggested fix: Make comments consistent.

---

5.2 --end-date -1d comment semantics may be inaccurate — gh aw logs (low)

Quoted CLI output: gh aw logs --end-date -1d # Download all runs until yesterday
Flag description: Filter runs created before this date (exclusive)
Suggested fix: # Download all runs created before yesterday

---

5.3 --watch flag placed before workflow name, inconsistent ordering — gh aw compile (low)

Quoted CLI output: gh aw compile --watch ci-doctor # Watch and auto-compile
Suggested fix: gh aw compile ci-doctor --watch # Watch and auto-compile

---

5.4 --no-release-bump example comment oversimplifies — gh aw update (medium)

Quoted CLI output: gh aw update --no-release-bump # Update without force-bumping all action versions
Flag description: Only disables non-core action bumps; actions/* are still force-updated.
Suggested fix: # Restrict force-updates to core actions/* only

---

Full Issues Table

#	Category	Severity	Command	Issue
1.1	grammar	low	validate	--fail-fast example omits "validation"
1.2	style	low	logs	Missing blank line before workflow-id paragraph
1.3	grammar	low	trial	workflow(s) inconsistent pluralization
1.4	style	medium	compile	"Unlike upgrade" sentence floats between sections
1.5	style	low	upgrade	"Flag behavior" bullets use lowercase openers
1.6	style	low	lint	Only command with zero inline example comments
1.7	style	low	fix	Numbered list steps missing terminal periods
2.1	flag-naming	medium	deploy	--repo different phrasing/format than all other commands
2.2	flag-naming	low	add, add-wizard, deploy, update, trial	--no-security-scanner uses "Disable" vs "Skip"
2.3	flag-naming	low	run/trial	--dry-run uses different verbs
2.4	flag-naming	low	update/upgrade	--no-compile missing qualifier in update
2.5	flag-naming	low	logs	--last omits -c short alias
3.1	docs-mismatch	HIGH	experiments	Documented in cli.md but entirely absent from CLI
3.2	style	medium	upgrade	Opening description vague, indistinguishable from update
3.3	style	medium	add	One-line description omits local files and URLs
3.4	docs-mismatch	medium	env get/env update	No standalone help sections
3.5	docs-mismatch	medium	secrets set/secrets bootstrap	No standalone help sections
4.1	docs-mismatch	low	run	Docs examples omit --dry-run
4.2	docs-mismatch	low	run	Docs description includes detail not in CLI
4.3	docs-mismatch	medium	secrets bootstrap	--non-interactive undiscoverable from help
4.4	example	low	forecast	daily-planner vs daily-plan inconsistency
5.1	example	medium	logs	--start-date comments inconsistent (10 runs vs all runs)
5.2	example	low	logs	--end-date -1d comment semantically inaccurate
5.3	example	low	compile	--watch flag ordering inconsistent with other examples
5.4	example	medium	update	--no-release-bump comment oversimplifies behavior

---

Inspection Metadata

Field	Value
Date	2026-07-10
Commands inspected	25 top-level + subcommands
Help output lines analyzed	1,562
Documentation file	docs/src/content/docs/setup/cli.md
Workflow run	29097140710
Method	Automated help collection + static analysis

Generated by ✅ CLI Consistency Checker · 135 AIC · ⌖ 9.38 AIC · ⊞ 4.4K · ◷

• expires on Jul 12, 2026, 5:59 AM UTC-08:00

[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 · 3.29 AIC · ⌖ 11.7 AIC · ⊞ 8.4K · ◷