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