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:184pkg/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 · ◷
Summary
Comprehensive inspection of the
gh awCLI tool identified 7 confirmed issues across help text accuracy, flag documentation, and docs/CLI alignment. Findings are grouped by severity below.**Inspection meta(redacted)
gh-aw --help+ all subcommand--helpoutput; comparison againstdocs/src/content/docs/setup/cli.mdSeverity breakdown
🔴 High Severity
1.
--yesflag description uses wrong verb inupdateandupgradeAffected commands:
update,upgradeCurrent CLI output (both commands):
Expected:
update:Auto-accept org-mode update confirmations (required in CI)upgrade:Auto-accept org-mode upgrade confirmations (required in CI)Reference (correct):
deploysaysAuto-accept org-mode deploy confirmations (required in CI)Source files:
pkg/cli/update_command.go:184pkg/cli/upgrade_command.go:161Suggested fix: Replace
createwithupdateinupdate_command.goand withupgradeinupgrade_command.go.2.
--dirflag omits$GH_AW_WORKFLOWS_DIRenv var in most commandsAffected commands:
compile,validate,fix,add,add-wizard,deploy,update,upgrade,remove(9 commands)Current CLI output (9 commands):
Correct output (only
lintandlist):Issue:
pkg/constants/constants.goGetWorkflowDir()reads$GH_AW_WORKFLOWS_DIRfor 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
lintandlist.3. Docs missing flags for
add-wizardcommandAffected:
docs/src/content/docs/setup/cli.md—add-wizardOptions sectionCurrent docs Options list for
add-wizard:Missing from docs (exist in CLI):
--append— appends to existing workflow file instead of overwriting--no-security-scanner— disables the security scannerSuggested fix: Add
--appendand--no-security-scannerto the Options table in theadd-wizarddocs section.🟡 Medium Severity
Medium severity findings (2)
4.
--timeoutflag description phrasing inconsistent acrosstrial,forecast,logsAffected commands:
trial,forecast,logstrialExecution timeout in minutes (set to 0 to disable timeout) (default 30)forecastGracefully stop forecast computation after this many minutes (0 disables timeout)logsDownload timeout in minutes (0 = no timeout)All three express the same "0 disables" concept differently. The
trialversion is the most verbose;logsis 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-rundescription phrasing inconsistent betweenrunandtrialAffected commands:
run,trialrunValidate workflow without actually triggering execution on GitHub ActionstrialPreview trial execution without applying any changesrunuses "Validate ... without actually triggering";trialuses "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.
lintshort description differs from its own full descriptionAffected command:
lintLint existing .lock.yml workflows with actionlint onlylint --helpLint 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:37Suggested fix: Unify to one canonical phrase — preferably the shorter one-liner style used consistently by other commands.
7.
--forceflag description varies across commandsAffected commands:
add,deploy,new,update,compile--forcedescriptionadd,deployOverwrite existing workflow files without confirmationnewOverwrite existing files without confirmation(missing "workflow")updateForce update even if no changes are detectedcompileForce overwrite of existing dependency filesnewis missing the word "workflow".updateandcompileuse semantically different meanings — worth verifying intent.Suggested fix: For
new, add "workflow" →Overwrite existing workflow files without confirmation. Forupdate/compile, verify if the semantic difference is intentional and document accordingly.