Skip to content

Fix CLI/docs consistency: document --shellcheck and --version, normalize update flag help #50280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Aug 4, 2026
Merged

Fix CLI/docs consistency: document --shellcheck and --version, normalize update flag help #50280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dad9859
Initial plan
Copilot Aug 4, 2026
f28ed87
Document --shellcheck/--version and normalize update flag descriptions
Copilot Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ The setup action installs the script at `/opt/gh-aw/actions/configure_gh_for_ghe
| `-h`, `--help` | Show help (`gh aw help [command]` for command-specific help) |
| `-v`, `--verbose` | Enable verbose output showing detailed information |
| `--banner` | Display ASCII logo banner with purple GitHub color theme |
| `--version` | Print the current version |

For invalid nested command paths, `gh aw` now fails explicitly instead of falling back to parent help output. For example, `gh aw secrets gh --help` returns an unknown-command error rather than reprinting `gh aw secrets` help.

Expand Down Expand Up @@ -335,7 +336,7 @@ If the repository root contains an [`aw.yml` manifest](/gh-aw/reference/aw-yml-p

Unlike `gh aw upgrade`, `gh aw compile` does not run codemods unless you pass `--fix`.

**Options:** `--action-mode`, `--action-tag`, `--actionlint`, `--actions-repo`, `--allow-action-refs`, `--approve`, `--dependabot`, `--dir/-d`, `--engine/-e`, `--fail-fast`, `--fix`, `--force/-f`, `--force-refresh-action-pins`, `--gh-aw-ref`, `--ghes`, `--grant`, `--grype`, `--json/-j`, `--logical-repo/-l`, `--no-check-update`, `--no-emit`, `--poutine`, `--purge`, `--refresh-stop-time`, `--runner-guard`, `--schedule-seed`, `--show-all`, `--staged`, `--stats`, `--strict`, `--syft`, `--trial`, `--validate`, `--validate-images`, `--watch/-w`, `--yamllint`, `--zizmor`
**Options:** `--action-mode`, `--action-tag`, `--actionlint`, `--actions-repo`, `--allow-action-refs`, `--approve`, `--dependabot`, `--dir/-d`, `--engine/-e`, `--fail-fast`, `--fix`, `--force/-f`, `--force-refresh-action-pins`, `--gh-aw-ref`, `--ghes`, `--grant`, `--grype`, `--json/-j`, `--logical-repo/-l`, `--no-check-update`, `--no-emit`, `--poutine`, `--purge`, `--refresh-stop-time`, `--runner-guard`, `--schedule-seed`, `--shellcheck`, `--show-all`, `--staged`, `--stats`, `--strict`, `--syft`, `--trial`, `--validate`, `--validate-images`, `--watch/-w`, `--yamllint`, `--zizmor`

**`--gh-aw-ref` flag:** Convenience alias for `--action-mode release --action-tag <ref>`. Accepts a branch name, tag, or commit SHA targeting the `github/gh-aw` repository. Branch and tag names are resolved to their full commit SHA at compile time, so the baked-in reference is immutable and reproducible. Useful for E2E-testing workflows compiled against a specific gh-aw revision.

Expand Down
10 changes: 5 additions & 5 deletions pkg/cli/update_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,19 +162,19 @@ Note: In GitHub Enterprise repos, shorthand source specs resolve on your enterpr
}

cmd.Flags().Bool("major", false, "Allow major version updates when updating tagged releases")
cmd.Flags().BoolP("force", "f", false, "Force update even if no changes are detected")
cmd.Flags().BoolP("force", "f", false, "Force update of workflow files even if no changes are detected")
addEngineFlag(cmd)
cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: $GH_AW_WORKFLOWS_DIR or .github/workflows)")
cmd.Flags().Bool("no-stop-after", false, "Remove any stop-after field from the workflow")
cmd.Flags().String("stop-after", "", "Override stop-after value in the workflow (e.g., '+48h', '2025-12-31 23:59:59')")
cmd.Flags().Bool("no-merge", false, "Override local changes with upstream version instead of merging")
cmd.Flags().Bool("no-release-bump", false, "Restrict automatic major version bumps to core actions/* only (non-core actions are left as-is)")
cmd.Flags().Bool("disable-release-bump", false, "Restrict automatic major version bumps to core actions/* only (non-core actions are left as-is)")
cmd.Flags().Bool("no-merge", false, "Skip merging; override local changes with the upstream version")
cmd.Flags().Bool("no-release-bump", false, "Skip automatic major version bumps for non-core actions (only core actions/* are bumped)")
cmd.Flags().Bool("disable-release-bump", false, "Skip automatic major version bumps for non-core actions (only core actions/* are bumped)")
Comment on lines +171 to +172
_ = cmd.Flags().MarkDeprecated("disable-release-bump", "use --no-release-bump instead")
addSecurityScannerFlag(cmd)
cmd.Flags().Bool("approve", false, "Approve all safe update changes. When strict mode is active (the default), the compiler emits warnings for new restricted secrets or unapproved action additions/removals not present in the existing gh-aw-manifest. Use this flag to approve and skip safe update enforcement")
cmd.Flags().Bool("no-compile", false, "Skip recompiling workflows during update (do not modify lock files)")
cmd.Flags().Bool("no-redirect", false, "Refuse updates when redirect frontmatter is present")
cmd.Flags().Bool("no-redirect", false, "Skip following redirects; refuse updates when redirect frontmatter is present")
cmd.Flags().String("org", "", "Preview or create workflow update pull requests across an organization")
cmd.Flags().StringSlice("repos", nil, "Limit --org mode to repositories matching one or more glob patterns")
addRepoFlag(cmd)
Expand Down