diff --git a/cmd/gh-aw/main.go b/cmd/gh-aw/main.go index 0ad0fa97311..1f39cc62b10 100644 --- a/cmd/gh-aw/main.go +++ b/cmd/gh-aw/main.go @@ -80,9 +80,9 @@ func validateEngine(engine string) error { var rootCmd = &cobra.Command{ Use: string(constants.CLIExtensionPrefix), - Short: "GitHub Agentic Workflows CLI from GitHub Next", + Short: "GitHub Agentic Workflows CLI", Version: version, - Long: `GitHub Agentic Workflows CLI from GitHub Next + Long: `GitHub Agentic Workflows CLI Common Tasks: ` + string(constants.CLIExtensionPrefix) + ` init # Set up a new repository @@ -811,7 +811,7 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all runCmd.Flags().String("ref", "", "Branch or tag name to run the workflow on (default: current branch)") runCmd.Flags().Bool("auto-merge-prs", false, "Auto-merge any pull requests created during the workflow execution") runCmd.Flags().StringArrayP("raw-field", "F", []string{}, "Pass a workflow dispatch input in key=value format (can be specified multiple times)") - _ = runCmd.Flags().MarkShorthandDeprecated("raw-field", "use --raw-field instead") + _ = runCmd.Flags().MarkShorthandDeprecated("raw-field", "use the long form --raw-field instead") runCmd.Flags().Bool("push", false, "Commit and push workflow files (including transitive imports) before running. Refuses to proceed when unrelated files are already staged.") runCmd.Flags().Bool("dry-run", false, "Preview workflow execution without triggering runs on GitHub Actions") runCmd.Flags().BoolP("json", "j", false, "Output results in JSON format") diff --git a/cmd/gh-aw/main_help_text_test.go b/cmd/gh-aw/main_help_text_test.go index 7c9cc5031f6..2f619a1d9f9 100644 --- a/cmd/gh-aw/main_help_text_test.go +++ b/cmd/gh-aw/main_help_text_test.go @@ -24,7 +24,7 @@ func TestRunCommandHelpTextConsistency(t *testing.T) { assert.Equal(t, "Approve safe update manifest changes when --push triggers an automatic recompile step. When strict mode is active (the default), the recompile step enforces safe update checking; pass this flag to approve those changes.", runApprove.Usage, "run --approve should explain the --push-triggered recompile behavior with strict mode context") assert.Equal(t, "Commit and push workflow files (including transitive imports) before running. Refuses to proceed when unrelated files are already staged.", runPush.Usage, "run --push should describe the staged-files precondition precisely") assert.Equal(t, "F", runRawField.Shorthand, "run --raw-field should keep the legacy -F shorthand for compatibility") - assert.Equal(t, "use --raw-field instead", runRawField.ShorthandDeprecated, "run -F shorthand should be marked deprecated") + assert.Equal(t, "use the long form --raw-field instead", runRawField.ShorthandDeprecated, "run -F shorthand should be marked deprecated") } func TestCompileScheduleSeedHelpUsesConsistentQuotes(t *testing.T) { diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 638f231a068..ba09d850294 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -263,7 +263,7 @@ gh aw secrets bootstrap --engine copilot # Check only Copilot se gh aw secrets bootstrap --non-interactive # Display missing secrets without prompting ``` -**Options:** `--engine` (copilot, claude, codex, gemini, antigravity, opencode, pi), `--non-interactive`, `--repo` +**Options:** `--engine/-e` (copilot, claude, codex, gemini, antigravity, opencode, pi), `--non-interactive`, `--repo` See [Authentication](/gh-aw/reference/auth/) for details. @@ -299,7 +299,7 @@ gh aw fix --list-codemods # List available codemods **Options:** `--dir/-d`, `--disable-codemod`, `--list-codemods`, `--write` -Use `--disable-codemod` (repeatable) to skip specific codemod IDs by name. +Use `--disable-codemod` (repeatable) to skip specific codemod IDs by name. Unlike the `--no-X` flags used elsewhere in the CLI (which toggle boolean options), `--disable-codemod` takes a codemod ID as its value and can be specified multiple times, so the `--no-codemod` pattern does not apply here. Available codemods include: @@ -331,7 +331,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`, `--json/-j`, `--logical-repo/-l`, `--no-check-update`, `--no-emit`, `--no-models-dev-lookup`, `--poutine`, `--purge`, `--refresh-stop-time`, `--runner-guard`, `--schedule-seed`, `--show-all`, `--staged`, `--stats`, `--strict`, `--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`, `--no-models-dev-lookup`, `--poutine`, `--purge`, `--refresh-stop-time`, `--runner-guard`, `--schedule-seed`, `--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 `. 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. @@ -345,6 +345,11 @@ Unlike `gh aw upgrade`, `gh aw compile` does not run codemods unless you pass `- **Strict Mode (`--strict`):** Enforces security best practices: no write permissions (use [safe-outputs](/gh-aw/reference/safe-outputs/)), explicit `network` config, no wildcard domains, pinned actions, no deprecated fields. See [Strict Mode reference](/gh-aw/reference/frontmatter/#strict-mode-strict). +**Security and Compliance Scanners:** +- **`--syft`:** Generates a Software Bill of Materials (SBOM) for container images referenced in compiled workflows using the Syft scanner. +- **`--grype`:** Scans container images referenced in compiled workflows for known vulnerabilities using the Grype vulnerability scanner. +- **`--runner-guard`:** Runs taint analysis on compiled workflows to detect unsafe data flows from untrusted inputs to sensitive runner operations. + **Shared Workflows:** Workflows without an `on` field are detected as shared components. Validated with relaxed schema and skip compilation. See [Imports reference](/gh-aw/reference/imports/). #### `validate` @@ -505,7 +510,7 @@ echo "1234567890" | gh aw logs --stdin --engine claude cat run-ids.txt | gh aw logs --stdin --repo owner/repo # required for bare numeric IDs ``` -**Options:** `--after-run-id`, `--artifacts`, `--before-run-id`, `--cache-before`, `--count/-c`, `--end-date`, `--engine/-e`, `--exclude-staged`, `--filtered-integrity`, `--firewall`, `--format`, `--json/-j`, `--last`, `--no-firewall`, `--output/-o`, `--parse`, `--ref`, `--report-file`, `--repo/-r`, `--safe-output`, `--start-date`, `--stdin`, `--summary-file`, `--timeout`, `--tool-graph`, `--train` +**Options:** `--after-run-id`, `--artifacts`, `--before-run-id`, `--cache-before`, `--count/-c`, `--end-date`, `--engine/-e`, `--evals`, `--exclude-staged`, `--filtered-integrity`, `--firewall`, `--format`, `--json/-j`, `--last`, `--no-firewall`, `--output/-o`, `--parse`, `--ref`, `--report-file`, `--repo/-r`, `--safe-output`, `--start-date`, `--stdin`, `--summary-file`, `--timeout`, `--tool-graph`, `--train` `logs` defaults `--artifacts` to `usage` for faster, compact downloads. The `--last` flag is an alias for `--count/-c`. @@ -842,6 +847,8 @@ Transfer pull request to another repository, preserving changes, title, and desc gh aw pr transfer --repo target-owner/target-repo ``` +**Options:** `--repo/-r` + #### `mcp-server` Run MCP server exposing gh-aw commands as tools. Spawns subprocesses to isolate GitHub tokens. diff --git a/pkg/cli/audit_diff_command.go b/pkg/cli/audit_diff_command.go index c68a74cf833..b36ed5e9024 100644 --- a/pkg/cli/audit_diff_command.go +++ b/pkg/cli/audit_diff_command.go @@ -18,7 +18,7 @@ import ( func NewAuditDiffSubcommand() *cobra.Command { cmd := &cobra.Command{ Use: "diff ...", - Short: "Compare behavior across workflow runs", + Short: "[Deprecated] Compare workflow runs (use: gh aw audit )", Hidden: true, Long: `Deprecated: pass multiple run IDs directly to the audit command instead. diff --git a/pkg/cli/doctor_command.go b/pkg/cli/doctor_command.go index c9db3f8c7b6..9786bfa25bb 100644 --- a/pkg/cli/doctor_command.go +++ b/pkg/cli/doctor_command.go @@ -59,7 +59,7 @@ target the correct host.`, }, } - cmd.Flags().StringP("repo", "r", "", "Target repository in [HOST/]owner/repo format") + cmd.Flags().StringP("repo", "r", "", "Target repository (owner/repo format)") cmd.Flags().StringP("dir", "d", "", "Checkout directory to inspect (defaults to the repo name)") cmd.Flags().String("require-owner-type", "any", "Require a specific owner type: any, org, or user") addJSONFlag(cmd) diff --git a/pkg/cli/env_command.go b/pkg/cli/env_command.go index 40e4d83e915..45b2461647d 100644 --- a/pkg/cli/env_command.go +++ b/pkg/cli/env_command.go @@ -113,7 +113,7 @@ var defaultsGetCurrentRepoSlug = GetCurrentRepoSlug func NewEnvCommand() *cobra.Command { cmd := &cobra.Command{ Use: "env", - Short: "Manage compiler defaults as GitHub variables", + Short: "Manage compiler defaults as GitHub Actions variables", Long: `Manage compiler default variables in bulk for a repository, organization, or enterprise scope. The YAML file is flat and uses default_-prefixed lowercase keys (e.g., default_max_turns). @@ -159,7 +159,7 @@ Scope resolution: } cmd.Flags().StringVar(&scope, "scope", "", "Variable scope (repo|org|ent). Defaults to repo") - cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository in owner/repo format. When omitted, defaults to current repository") + cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository (owner/repo format). Defaults to current repository") cmd.Flags().StringVar(&org, "org", "", "Target organization (required for --scope org unless inferable from --repo/current repo)") cmd.Flags().StringVar(&enterprise, "enterprise", "", "Target enterprise slug (required for --scope ent)") return cmd @@ -198,7 +198,7 @@ Scope and flag behavior: } cmd.Flags().StringVar(&scope, "scope", "", "Variable scope (repo|org|ent)") - cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository in owner/repo format. When omitted, defaults to current repository") + cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository (owner/repo format). Defaults to current repository") cmd.Flags().StringVar(&org, "org", "", "Target organization (required for --scope org unless inferable from --repo/current repo)") cmd.Flags().StringVar(&enterprise, "enterprise", "", "Target enterprise slug (required for --scope ent)") cmd.Flags().BoolVarP(&yes, "yes", "y", false, "Skip confirmation prompt") diff --git a/pkg/cli/lint_command.go b/pkg/cli/lint_command.go index 635f8e12e0a..7a2b81429eb 100644 --- a/pkg/cli/lint_command.go +++ b/pkg/cli/lint_command.go @@ -34,7 +34,7 @@ var defaultGhAwActionlintIgnorePatterns = []string{ func NewLintCommand() *cobra.Command { cmd := &cobra.Command{ Use: "lint [lock-file-or-directory]...", - Short: "Lint existing .lock.yml workflows with actionlint only", + Short: "Lint existing .lock.yml workflow files with actionlint only", Long: `Lint existing .lock.yml workflow files from disk using actionlint only. This command does not recompile Markdown workflows and does not run zizmor or poutine. diff --git a/pkg/cli/mcp_server_command.go b/pkg/cli/mcp_server_command.go index 8ba7f191dea..ec609227d77 100644 --- a/pkg/cli/mcp_server_command.go +++ b/pkg/cli/mcp_server_command.go @@ -19,7 +19,7 @@ func NewMCPServerCommand() *cobra.Command { cmd := &cobra.Command{ Use: "mcp-server", - Short: "Run an MCP (Model Context Protocol) server exposing gh aw commands as tools", + Short: "Run an MCP server that exposes gh aw CLI commands as MCP tools", Long: `Run an MCP server that exposes gh aw CLI commands as MCP tools. This command starts an MCP server that wraps the gh aw CLI. It spawns a subprocess for each tool invocation to ensure that GitHub tokens and other diff --git a/pkg/cli/validate_command.go b/pkg/cli/validate_command.go index dc4a556a3e1..2c406e964b6 100644 --- a/pkg/cli/validate_command.go +++ b/pkg/cli/validate_command.go @@ -76,7 +76,7 @@ If no workflows are specified, all Markdown files in .github/workflows will be v addEngineFlag(cmd) cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: $GH_AW_WORKFLOWS_DIR or .github/workflows)") cmd.Flags().Bool("strict", false, "Override frontmatter to enforce strict mode validation for all workflows (enforces action pinning, network config, safe-outputs, disallows write permissions and deprecated fields). Note: Workflows default to strict mode unless frontmatter sets strict: false") - cmd.Flags().BoolP("json", "j", false, "Output results in JSON format") + addJSONFlag(cmd) cmd.Flags().Bool("fail-fast", false, "Stop at the first validation error instead of collecting all errors") cmd.Flags().Bool("validate-images", false, "Require Docker to be available for container image validation. Without this flag, container image validation is silently skipped when Docker is not installed or the daemon is not running") cmd.Flags().Bool("stats", false, "Display statistics table sorted by workflow file size (shows jobs, steps, scripts, and shells)")