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

[github-actions]

Summary

Comprehensive inspection of the gh aw CLI tool identified 7 confirmed issues across help text accuracy, flag documentation, and docs/CLI alignment. Findings are grouped by severity below.

**Inspection meta(redacted)

• Commands inspected: 34
• Date: 2026-07-07
• Method: gh-aw --help + all subcommand --help output; comparison against docs/src/content/docs/setup/cli.md
• Workflow run: 28871251654

Severity breakdown

Severity	Count
🔴 High	3
🟡 Medium	2
🟢 Low	2
Total	7

---

🔴 High Severity

1. --yes flag description uses wrong verb in update and upgrade

Affected commands: update, upgrade

Current CLI output (both commands):

-y, --yes   Auto-accept org-mode create confirmations (required in CI)

Expected:

• update: Auto-accept org-mode update confirmations (required in CI)
• upgrade: Auto-accept org-mode upgrade confirmations (required in CI)

Reference (correct): deploy says Auto-accept org-mode deploy confirmations (required in CI)

Source files:

• pkg/cli/update_command.go:184
• pkg/cli/upgrade_command.go:161

Suggested fix: Replace create with update in update_command.go and with upgrade in upgrade_command.go.

---

2. --dir flag omits $GH_AW_WORKFLOWS_DIR env var in most commands

Affected commands: compile, validate, fix, add, add-wizard, deploy, update, upgrade, remove (9 commands)

Current CLI output (9 commands):

-d, --dir string   Workflow directory (default ".github/workflows")

Correct output (only lint and list):

-d, --dir string   Workflow directory (default: $GH_AW_WORKFLOWS_DIR or .github/workflows)

Issue: pkg/constants/constants.go GetWorkflowDir() reads $GH_AW_WORKFLOWS_DIR for all commands, but 9 commands silently omit this from their flag help text, making the env var undiscoverable in the CLI.

Suggested fix: Update all 9 affected commands to use the same description format as lint and list.

---

3. Docs missing flags for add-wizard command

Affected: docs/src/content/docs/setup/cli.md — add-wizard Options section

Current docs Options list for add-wizard:

--no-secret, --dir/-d, --engine/-e, --no-gitattributes, --no-stop-after, --stop-after

Missing from docs (exist in CLI):

• --append — appends to existing workflow file instead of overwriting
• --no-security-scanner — disables the security scanner

Suggested fix: Add --append and --no-security-scanner to the Options table in the add-wizard docs section.

---

🟡 Medium Severity

Medium severity findings (2)

4. --timeout flag description phrasing inconsistent across trial, forecast, logs

Affected commands: trial, forecast, logs

Command	Current description
trial	Execution timeout in minutes (set to 0 to disable timeout) (default 30)
forecast	Gracefully stop forecast computation after this many minutes (0 disables timeout)
logs	Download timeout in minutes (0 = no timeout)

All three express the same "0 disables" concept differently. The trial version is the most verbose; logs is inconsistently terse.

Suggested fix: Standardise to a single pattern, e.g. (0 = no timeout) or (set to 0 to disable) — pick one and apply to all three.

---

5. --dry-run description phrasing inconsistent between run and trial

Affected commands: run, trial

Command	Current description
run	Validate workflow without actually triggering execution on GitHub Actions
trial	Preview trial execution without applying any changes

run uses "Validate ... without actually triggering"; trial uses "Preview ... without applying any changes". Both flags skip real side-effects but use unrelated phrasing.

Suggested fix: Align both to the same style, e.g. Dry-run: validate/preview without triggering real execution.

---

🟢 Low Severity

Low severity findings (2)

6. lint short description differs from its own full description

Affected command: lint

Context	Text
Main help listing	Lint existing .lock.yml workflows with actionlint only
lint --help	Lint existing .lock.yml workflow files from disk using actionlint only.

The full description adds "files from disk" and ends with a period, while the one-liner omits those words and has no period.

Source file: pkg/cli/lint_command.go:37

Suggested fix: Unify to one canonical phrase — preferably the shorter one-liner style used consistently by other commands.

---

7. --force flag description varies across commands

Affected commands: add, deploy, new, update, compile

Command	--force description
add, deploy	Overwrite existing workflow files without confirmation
new	Overwrite existing files without confirmation (missing "workflow")
update	Force update even if no changes are detected
compile	Force overwrite of existing dependency files

new is missing the word "workflow". update and compile use semantically different meanings — worth verifying intent.

Suggested fix: For new, add "workflow" → Overwrite existing workflow files without confirmation. For update/compile, verify if the semantic difference is intentional and document accordingly.

---

Note: A typo/grammar extraction agent was launched as part of this inspection run but had not completed at time of issue creation. If additional grammar or punctuation issues are found, this issue should be updated.

Generated by ✅ CLI Consistency Checker · 377.5 AIC · ⌖ 14.3 AIC · ⊞ 4.4K · ◷

• expires on Jul 9, 2026, 6:05 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 · 1.02 AIC · ⌖ 4.58 AIC · ⊞ 6.3K · ◷