Align CLI help/grouping and flag semantics for command consistency

cmd/gh-aw/command_groups_test.go

@@ -46,7 +46,11 @@ func TestCommandGroupAssignments(t *testing.T) {
 		{name: "status command in analysis group", commandName: "status", expectedGroup: "analysis", shouldHaveGroup: true},
 		{name: "list command in analysis group", commandName: "list", expectedGroup: "analysis", shouldHaveGroup: true},
 		{name: "health command in analysis group", commandName: "health", expectedGroup: "analysis", shouldHaveGroup: true},
+		{name: "outcomes command in analysis group", commandName: "outcomes", expectedGroup: "analysis", shouldHaveGroup: true},
 		{name: "checks command in analysis group", commandName: "checks", expectedGroup: "analysis", shouldHaveGroup: true},
+		// Hidden commands should still be grouped so they appear in the correct
+		// section when explicitly shown (for example in full help/test contexts).
+		{name: "view command in analysis group", commandName: "view", expectedGroup: "analysis", shouldHaveGroup: true},
 		{name: "experiments command in analysis group", commandName: "experiments", expectedGroup: "analysis", shouldHaveGroup: true},
 
 		// Utilities

cmd/gh-aw/compile_flags_test.go

@@ -0,0 +1,23 @@
+//go:build !integration
+
+package main
+
+import "testing"
+
+func TestCompileCommandShortFlags(t *testing.T) {
+	forceFlag := compileCmd.Flags().Lookup("force")
+	if forceFlag == nil {
+		t.Fatal("expected --force flag on compile command")
+	}
+	if forceFlag.Shorthand != "f" {
+		t.Fatalf("expected --force shorthand to be -f, got -%s", forceFlag.Shorthand)
+	}
+
+	logicalRepoFlag := compileCmd.Flags().Lookup("logical-repo")
+	if logicalRepoFlag == nil {
+		t.Fatal("expected --logical-repo flag on compile command")
+	}
+	if logicalRepoFlag.Shorthand != "l" {
+		t.Fatalf("expected --logical-repo shorthand to be -l, got -%s", logicalRepoFlag.Shorthand)
+	}
+}

cmd/gh-aw/main.go

@@ -90,8 +90,9 @@ Common Tasks:
   gh aw new my-workflow       # Create your first workflow
   gh aw compile               # Compile all workflows
   gh aw run my-workflow       # Execute a workflow
+  gh aw status                # Check workflow status
   gh aw logs my-workflow      # View execution logs
-  gh aw audit <run-id-or-url> # Debug a failed run
+  gh aw audit <run-id-or-url> # Audit and compare workflow runs
 
 For detailed help on any command, use:
   gh aw [command] --help`,
@@ -725,14 +726,14 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	compileCmd.Flags().Bool("purge", false, "Delete .lock.yml files that were not regenerated during compilation (only when no specific files are specified)")
 	compileCmd.Flags().Bool("strict", false, "Override frontmatter to enforce strict mode validation for all workflows (enforces action pinning, network config, safe-outputs, refuses write permissions and deprecated fields). Note: Workflows default to strict mode unless frontmatter sets strict: false")
 	compileCmd.Flags().Bool("trial", false, "Enable trial mode compilation (modifies workflows for trial execution)")
-	compileCmd.Flags().String("logical-repo", "", "Repository to simulate workflow execution against (for trial mode)")
+	compileCmd.Flags().StringP("logical-repo", "l", "", "Repository to simulate workflow execution against (for trial mode)")
 	compileCmd.Flags().Bool("use-samples", false, "Hidden: replace the agentic 'Execute coding agent' step with a deterministic driver that replays the workflow's safe-outputs `samples` frontmatter entries through the safe-outputs MCP server. Used to make end-to-end tests deterministic.")
 	_ = compileCmd.Flags().MarkHidden("use-samples")
 	compileCmd.Flags().Bool("dependabot", false, "Generate dependency manifests (package.json, requirements.txt, go.mod) and Dependabot config when dependencies are detected")
-	compileCmd.Flags().Bool("force", false, "Force overwrite of existing dependency files (e.g., dependabot.yml)")
+	compileCmd.Flags().BoolP("force", "f", false, "Force overwrite of existing dependency files (e.g., dependabot.yml)")
 	compileCmd.Flags().Bool("refresh-stop-time", false, "Force regeneration of stop-after times instead of preserving existing values from lock files")
 	compileCmd.Flags().Bool("force-refresh-action-pins", false, "Force refresh of action pins by clearing the cache and resolving all action SHAs from GitHub API")
-	compileCmd.Flags().Bool("allow-action-refs", false, "Allow unresolved action refs and emit warnings instead of failing compilation")
+	compileCmd.Flags().Bool("allow-action-refs", false, "Allow unresolved action refs and emit warnings instead of failing validation")
 	compileCmd.Flags().Bool("zizmor", false, "Run zizmor security scanner on generated .lock.yml files")
 	compileCmd.Flags().Bool("poutine", false, "Run poutine security scanner on generated .lock.yml files")
 	compileCmd.Flags().Bool("actionlint", false, "Run actionlint linter on generated .lock.yml files")
@@ -808,6 +809,7 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	auditCmd := cli.NewAuditCommand()
 	viewCmd := cli.NewViewCommand()
 	healthCmd := cli.NewHealthCommand()
+	outcomesCmd := cli.NewOutcomesCommand()
 	mcpServerCmd := cli.NewMCPServerCommand()
 	prCmd := cli.NewPRCommand()
 	secretsCmd := cli.NewSecretsCommand()
@@ -844,8 +846,6 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	mcpCmd.GroupID = "development"
 	fixCmd.GroupID = "development"
 	domainsCmd.GroupID = "development"
-	statusCmd.GroupID = "analysis"
-	listCmd.GroupID = "analysis"
 
 	// Execution Commands
 	runCmd.GroupID = "execution"
@@ -858,7 +858,10 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	auditCmd.GroupID = "analysis"
 	viewCmd.GroupID = "analysis"
 	healthCmd.GroupID = "analysis"
+	outcomesCmd.GroupID = "analysis"
 	checksCmd.GroupID = "analysis"
+	statusCmd.GroupID = "analysis"
+	listCmd.GroupID = "analysis"
 	experimentsCmd.GroupID = "analysis"
 	forecastCmd.GroupID = "analysis"
 
@@ -887,7 +890,6 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	rootCmd.AddCommand(listCmd)
 	rootCmd.AddCommand(enableCmd)
 	rootCmd.AddCommand(disableCmd)
-	outcomesCmd := cli.NewOutcomesCommand()
 	rootCmd.AddCommand(logsCmd)
 	rootCmd.AddCommand(auditCmd)
 	rootCmd.AddCommand(viewCmd)

docs/src/content/docs/setup/cli.md

@@ -20,7 +20,7 @@ The `gh aw` CLI extension enables developers to create, manage, and execute AI-p
 | [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions |
 | [`gh aw status`](#status) | Check current state of all workflows |
 | [`gh aw logs`](#logs) | Download and analyze workflow logs |
-| [`gh aw audit`](#audit) | Debug a failed workflow run |
+| [`gh aw audit`](#audit) | Audit and compare workflow runs |
 
 ## Installation
 
@@ -168,7 +168,7 @@ Add workflows from The Agentics collection or other repositories to `.github/wor
 ```bash wrap
 gh aw add githubnext/agentics/ci-doctor           # Add single workflow
 gh aw add githubnext/agentics/ci-doctor@v1.0.0   # Add specific version
-gh aw add githubnext/agentics/ci-doctor --dir shared                  # Organize in subdirectory
+gh aw add githubnext/agentics/ci-doctor --dir .github/workflows/shared  # Organize in subdirectory
 gh aw add githubnext/agentics/ci-doctor --create-pull-request        # Create PR instead of commit
 gh aw add https://example.com/workflows/my-workflow.md               # Arbitrary HTTPS URL (markdown)
 gh aw add https://example.com/workflows/my-workflow.json             # Arbitrary HTTPS URL (JSON workflow definition)
@@ -293,7 +293,7 @@ gh aw compile --purge                      # Remove orphaned .lock.yml files
 
 If the repository root contains an [`aw.yml` manifest](/gh-aw/reference/aw-yml-package-manifest/), `gh aw compile` validates it before compiling workflows.
 
-**Options:** `--action-mode`, `--action-tag`, `--actionlint`, `--actions-repo`, `--allow-action-refs`, `--approve`, `--dependabot`, `--dir/-d`, `--engine/-e`, `--fail-fast`, `--fix`, `--force`, `--force-refresh-action-pins`, `--gh-aw-ref`, `--ghes`, `--json/-j`, `--logical-repo`, `--no-check-update`, `--no-emit`, `--poutine`, `--purge`, `--refresh-stop-time`, `--runner-guard`, `--schedule-seed`, `--show-all`, `--staged`, `--stats`, `--strict`, `--trial`, `--validate`, `--validate-images`, `--watch/-w`, `--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`, `--json/-j`, `--logical-repo/-l`, `--no-check-update`, `--no-emit`, `--poutine`, `--purge`, `--refresh-stop-time`, `--runner-guard`, `--schedule-seed`, `--show-all`, `--staged`, `--stats`, `--strict`, `--trial`, `--validate`, `--validate-images`, `--watch/-w`, `--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.
 
@@ -466,7 +466,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`, `--filtered-integrity`, `--firewall`, `--format`, `--json/-j`, `--last`, `--no-firewall`, `--no-staged`, `--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`, `--filtered-integrity`, `--firewall`, `--format`, `--json/-j`, `--last`, `--no-firewall`, `--no-staged`, `--output/-o`, `--parse`, `--ref`, `--report-file`, `--repo/-r`, `--safe-output`, `--start-date`, `--stdin`, `--summary-file`, `--timeout`, `--tool-graph`, `--train`
 
 #### `audit`
 
@@ -591,7 +591,7 @@ Maps PR check rollups to one of the following normalized states: `success`, `fai
 
 #### `forecast` `[EXPERIMENTAL]`
 
-Forecast AI Credit (AIC) usage and costs for agentic workflows using recent run history and Monte Carlo simulation.
+Forecast AI Credit (AIC) usage for agentic workflows using recent run history and Monte Carlo simulation.
 
 ```bash wrap
 gh aw forecast                              # Forecast all workflows (monthly)
@@ -716,7 +716,7 @@ gh aw env get org-defaults.yml --scope org --org my-org
 gh aw env get ent-defaults.yml --scope ent --enterprise my-enterprise
 ```
 
-**Options:** `--scope`, `--repo`, `--org`, `--enterprise`
+**Options:** `--scope`, `--repo/-r`, `--org`, `--enterprise`
 
 ##### `env update [file]`
 
@@ -728,7 +728,7 @@ gh aw env update defaults.yml --scope org --org my-org --dry-run
 gh aw env update defaults.yml --scope ent --enterprise my-enterprise --yes
 ```
 
-**Options:** `--scope` (required), `--repo`, `--org`, `--enterprise`, `--yes/-y`, `--dry-run`
+**Options:** `--scope` (required), `--repo/-r`, `--org`, `--enterprise`, `--yes/-y`, `--dry-run`
 
 ### Advanced
 

pkg/cli/env_command.go

@@ -159,7 +159,7 @@ Scope resolution:
 	}
 
 	cmd.Flags().StringVar(&scope, "scope", "", "Variable scope (repo|org|ent). Defaults to repo")
-	cmd.Flags().StringVar(&repo, "repo", "", "Target repository in owner/repo format")
+	cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository in owner/repo format. When omitted, 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().StringVar(&repo, "repo", "", "Target repository in owner/repo format")
+	cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository in owner/repo format. When omitted, 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")

pkg/cli/env_command_test.go

@@ -43,6 +43,14 @@ func TestNewEnvCommand(t *testing.T) {
 	assert.Contains(t, updateCmd.Long, "--yes")
 	assert.NotNil(t, updateCmd.Flags().Lookup("yes"))
 	assert.NotNil(t, updateCmd.Flags().Lookup("dry-run"))
+
+	getRepoFlag := getCmd.Flags().Lookup("repo")
+	require.NotNil(t, getRepoFlag)
+	assert.Equal(t, "r", getRepoFlag.Shorthand)
+
+	updateRepoFlag := updateCmd.Flags().Lookup("repo")
+	require.NotNil(t, updateRepoFlag)
+	assert.Equal(t, "r", updateRepoFlag.Shorthand)
 }
 
 func TestResolveDefaultsTarget(t *testing.T) {

pkg/cli/fix_command.go

@@ -82,7 +82,7 @@ all steps and additionally:
 	cmd.Flags().Bool("write", false, "Write changes to files (without this flag, no changes are made)")
 	cmd.Flags().Bool("list-codemods", false, "List all available codemods and exit")
 	cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: .github/workflows)")
-	cmd.Flags().StringSlice("disable-codemod", nil, "Disable specific codemod IDs (repeatable)")
+	cmd.Flags().StringSlice("disable-codemod", nil, "Disable specific codemod IDs during the fix step (repeatable)")
 
 	// Register completions
 	cmd.ValidArgsFunction = CompleteWorkflowNames

pkg/cli/flags.go

@@ -17,7 +17,7 @@ func addEngineFlag(cmd *cobra.Command) {
 // addEngineFilterFlag adds the --engine/-e flag to a command for filtering.
 // This flag allows filtering results by AI engine type.
 func addEngineFilterFlag(cmd *cobra.Command) {
-	cmd.Flags().StringP("engine", "e", "", engineFlagUsage("Filter logs by AI engine"))
+	cmd.Flags().String("engine", "", engineFlagUsage("Filter logs by AI engine"))
 }
 
 // addRepoFlag adds the --repo/-r flag to a command.

pkg/cli/flags_test.go

@@ -59,6 +59,14 @@ func TestShortFlagConsistency(t *testing.T) {
 			shouldExist:  true,
 			description:  "update should have force short flag",
 		},
+		{
+			name:         "compile command has -f for --force",
+			shortFlag:    "f",
+			longFlag:     "force",
+			commandSetup: func() *cobra.Command { return createCompileCommandStub() },
+			shouldExist:  true,
+			description:  "compile should have force short flag",
+		},
 
 		// -F flag (raw-field in run command)
 		{
@@ -147,6 +155,14 @@ func TestShortFlagConsistency(t *testing.T) {
 			shouldExist:  true,
 			description:  "update should have dir short flag",
 		},
+		{
+			name:         "compile command has -l for --logical-repo",
+			shortFlag:    "l",
+			longFlag:     "logical-repo",
+			commandSetup: func() *cobra.Command { return createCompileCommandStub() },
+			shouldExist:  true,
+			description:  "compile should have logical-repo short flag",
+		},
 
 		// -c flag (count) - should only be in logs command
 		{
@@ -175,6 +191,14 @@ func TestShortFlagConsistency(t *testing.T) {
 			shouldExist:  true,
 			description:  "disable should have repo short flag",
 		},
+		{
+			name:         "logs command does not have -e for --engine",
+			shortFlag:    "e",
+			longFlag:     "engine",
+			commandSetup: func() *cobra.Command { return NewLogsCommand() },
+			shouldExist:  false,
+			description:  "logs should not have engine short flag",
+		},
 
 		// -w flag (watch)
 		{
@@ -233,8 +257,10 @@ func TestShortFlagConsistency(t *testing.T) {
 func createCompileCommandStub() *cobra.Command {
 	cmd := &cobra.Command{Use: "compile"}
 	cmd.Flags().StringP("engine", "e", "", "Override AI engine")
+	cmd.Flags().BoolP("force", "f", false, "Force overwrite")
 	cmd.Flags().BoolP("watch", "w", false, "Watch for changes")
 	cmd.Flags().StringP("dir", "d", "", "Workflow directory")
+	cmd.Flags().StringP("logical-repo", "l", "", "Repository to simulate")
 	cmd.Flags().BoolP("json", "j", false, "Output results in JSON format")
 	return cmd
 }

pkg/cli/forecast_command.go

@@ -35,7 +35,7 @@ type ForecastConfig struct {
 func NewForecastCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "forecast [workflow]...",
-		Short: "Forecast AI Credit usage and costs for agentic workflows (experimental)",
+		Short: "[EXPERIMENTAL] Forecast AI Credit (AIC) usage for agentic workflows",
 		Long: `[EXPERIMENTAL] Forecast AI Credit (AIC) usage for agentic workflows by sampling
 recent run history and projecting forward on a per-week or per-month basis.
 

pkg/cli/logs_command.go

@@ -31,7 +31,7 @@ func NewLogsCommand() *cobra.Command {
 
 	logsCmd := &cobra.Command{
 		Use:   "logs [workflow]",
-		Short: "Download and analyze agentic workflow logs with aggregated metrics",
+		Short: "Download and analyze agentic workflow logs and artifacts",
 		Long: fmt.Sprintf(`Download and analyze agentic workflow logs and artifacts from GitHub Actions.
 
 This command fetches workflow runs, downloads their artifacts, and extracts them into

pkg/cli/logs_command_test.go

@@ -17,7 +17,7 @@ func TestNewLogsCommand(t *testing.T) {
 
 	require.NotNil(t, cmd, "NewLogsCommand should not return nil")
 	assert.Equal(t, "logs [workflow]", cmd.Use, "Command use should be 'logs [workflow]'")
-	assert.Equal(t, "Download and analyze agentic workflow logs with aggregated metrics", cmd.Short, "Command short description should match")
+	assert.Equal(t, "Download and analyze agentic workflow logs and artifacts", cmd.Short, "Command short description should match")
 	assert.Contains(t, cmd.Long, "Download and analyze agentic workflow logs", "Command long description should contain expected text")
 	assert.Contains(t, cmd.Example, "logs --cache-before -1w", "Cache maintenance examples should use the cache-before flag name")
 
@@ -40,6 +40,7 @@ func TestNewLogsCommand(t *testing.T) {
 	// Check engine flag
 	engineFlag := flags.Lookup("engine")
 	assert.NotNil(t, engineFlag, "Should have 'engine' flag")
+	assert.Empty(t, engineFlag.Shorthand, "Engine filter flag should not have shorthand")
 
 	// Check firewall flags
 	firewallFlag := flags.Lookup("firewall")

pkg/cli/logs_filtering_test.go

@@ -74,9 +74,10 @@ func TestLogsCommandFlags(t *testing.T) {
 		t.Errorf("Expected engine flag default value to be empty, got: %s", engineFlag.DefValue)
 	}
 
-	// Test that engine flag has the -e shorthand for consistency with other commands
-	if engineFlag.Shorthand != "e" {
-		t.Errorf("Expected engine flag shorthand to be 'e', got: %s", engineFlag.Shorthand)
+	// Engine filter flag intentionally has no shorthand to avoid conflicting
+	// semantics with override-style --engine/-e flags on mutating commands.
+	if engineFlag.Shorthand != "" {
+		t.Errorf("Expected engine flag shorthand to be empty, got: %s", engineFlag.Shorthand)
 	}
 }