Skip to content

[cli-consistency] CLI Consistency Issues - 2026-06-19Β #40321

Description

@github-actions

Summary

Automated CLI consistency inspection (2026-06-19) against the gh-aw binary and docs/src/content/docs/setup/cli.md. 34 commands inspected, 20 issues found.

Severity Count
πŸ”΄ High 1
🟑 Medium 7
🟒 Low 12

πŸ”΄ High

H1 β€” --dry-run semantics differ between run and trial

  • run --dry-run: "Validate workflow without actually triggering execution on GitHub Actions"
  • trial --dry-run: "Show what would be done without making any changes"

trial --dry-run is broader (no changes at all) while run --dry-run only skips dispatch. Users expect consistent semantics. Fix: align descriptions or rename trial's variant to --plan/--preview.


🟑 Medium

M1 β€” Missing article in --append flag (3 commands: add, deploy, trial)

Text: "Append extra content to the end of agentic workflow on installation" β†’ missing "the" before "agentic workflow".

M2 β€” Missing article in trial help body

"All workflows must support workflow_dispatch trigger to be used in trial mode." β†’ missing "the" before "workflow_dispatch trigger".

M3 β€” --stdin descriptions differ between audit and logs

  • audit: "...instead of positional arguments"
  • logs: "...instead of discovering runs via the GitHub API"
    Same flag, different explanations. Fix: unify wording.

M4 β€” --dir description inconsistent: lint vs all others

  • Others: "Workflow directory (default: .github/workflows)"
  • lint: "Directory to scan for *.lock.yml files when no arguments are provided (default \".github/workflows\")"
    Fix: normalize phrasing and default-value style.

M5 β€” --logical-repo short flag -l only on trial, not compile

Both commands have --logical-repo but only trial exposes -l. Descriptions also diverge. Fix: add -l to compile or remove it from trial; unify descriptions.

M6 β€” --force covers three different behaviors

  • add/deploy/new: overwrite files
  • update: force update even without changes
  • compile: overwrite dependency files only
    Fix: rename specialized variants (--force-update, --force-deps) or add inline disambiguation.

M7 β€” --verbose docs vs CLI mismatch

  • Docs: "Enable verbose output with debugging details"
  • CLI: "Enable verbose output showing detailed information"
    Fix: align both to the same wording.

🟒 Low (12 issues)

L1 β€” "VSCode" β†’ "VS Code" in init help

"Configures VSCode settings (.vscode/settings.json)" β€” incorrect brand capitalization.

L2 β€” Missing "the" before "expires field" in init help

"if any workflows use expires field for discussions or issues" β†’ "the expires field"

L3 β€” Awkward phrasing in init Codespaces bullet

"- Adds GitHub Copilot extensions and gh aw CLI installation" β†’ "...and installs the gh aw CLI"

L4 β€” Missing "the" before "GitHub API" in compile help

"resolving all action SHAs from GitHub API" β†’ "from the GitHub API"

L5 β€” Missing "an" before "HTTP server" in mcp-server example comment

"# Run HTTP server on port 8080..." β†’ "# Run an HTTP server..."

L6 β€” health CLI help omits token usage and costs

Docs mention "token usage, costs" as health outputs, but gh aw health --help doesn't list them. Fix: add the bullet or remove from docs.

L7 β€” trial --append says "on installation" β€” wrong context

trial is not an install command. Fix: change to "...before running" for trial.

L8 β€” --auto-merge-prs wording differs between run and trial

  • run: "during the workflow execution" / trial: "during trial execution" β€” trivial inconsistency; unify.

L9 β€” --days allowed values not stated consistently

forecast --days: "(allowed values: 7, 30)" vs health --days: "(7, 30, or 90)" β€” different constraints, different styles. Fix: both should clearly state allowed values in the same format.

L10 β€” --timeout zero-value semantics inconsistent across 3 commands

  • forecast: "(0 disables timeout)" / trial: "(default 30)" / logs: "(0 = no timeout)" β€” normalize zero-value documentation.

L11 β€” --format default style inconsistent: audit vs logs

  • audit: flag annotation shows (default "pretty")
  • logs: prose "Default: compact agent-optimized output"
    Fix: use consistent style across both.

L12 β€” --output/-o default missing in outcomes

audit and logs both document (default ".github/aw/logs") but outcomes --output omits the default. Fix: add default annotation.


Metadata

Item Value
Date 2026-06-19
Workflow run 27830699006
Docs file docs/src/content/docs/setup/cli.md
Method CLI --help collection + sub-agent analysis + manual diff

Generated by βœ… CLI Consistency Checker Β· 120.2 AIC Β· βŒ– 7.75 AIC Β· ⊞ 4.2K Β· β—·

  • expires on Jun 21, 2026, 6:21 AM UTC-08:00

Metadata

Metadata

Labels

automationclicookieIssue Monster Loves Cookies!documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions