github · pelikhan · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026
diff --git a/cmd/gh-aw/main.go b/cmd/gh-aw/main.go
@@ -119,7 +119,7 @@ When called with a workflow name, creates a template file with comprehensive exa
 - All trigger types (on: events)
 - Permissions configuration
 - AI engine settings
-- Tools configuration (github, claude, MCPs)
+- Tools configuration (GitHub, Claude, MCPs)
 - All frontmatter options with explanations
 
 ` + cli.WorkflowIDExplanation,
@@ -727,7 +727,7 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	compileCmd.Flags().String("workflows-dir", "", "Deprecated: use --dir instead")
 	_ = compileCmd.Flags().MarkDeprecated("workflows-dir", "use --dir instead")
 	compileCmd.Flags().Bool("no-emit", false, "Validate workflow without generating lock files")
-	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("purge", false, "Delete .lock.yml files that were not regenerated during compilation (only when no specific files are provided)")
 	compileCmd.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")
 	compileCmd.Flags().Bool("trial", false, "Enable trial mode compilation (modifies workflows for trial execution)")
 	compileCmd.Flags().StringP("logical-repo", "l", "", "Repository to simulate workflow execution against (for trial mode)")

diff --git a/docs/adr/29170-stdin-input-mode-for-logs-and-audit-commands.md b/docs/adr/29170-stdin-input-mode-for-logs-and-audit-commands.md
@@ -64,7 +64,7 @@ A `--file` flag could accept a path to a text file containing run IDs. This is m
 
 ### Flag Interactions
 
-1. Content-filtering flags (`--engine`, `--firewall`, `--no-firewall`, `--safe-output`, `--filtered-integrity`, `--no-staged`) **MUST** apply to runs supplied via stdin in the same way they apply to runs discovered via the GitHub API.
+1. Content-filtering flags (`--engine`, `--firewall`, `--no-firewall`, `--safe-output`, `--filtered-integrity`, `--exclude-staged`) **MUST** apply to runs supplied via stdin in the same way they apply to runs discovered via the GitHub API.
 2. Discovery-scoping flags that are meaningless without API discovery (`--count`, `--date`, `--after`, workflow-name positional argument) **SHOULD NOT** silently take effect in stdin mode; implementations **SHOULD** document that these flags are ignored when `--stdin` is set.
 
 ### Conformance

diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
@@ -485,7 +485,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`, `--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/-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`
 
 `logs` defaults `--artifacts` to `usage` for faster, compact downloads. The `--last` flag is an alias for `--count/-c`.
 

diff --git a/pkg/cli/add_command.go b/pkg/cli/add_command.go
@@ -179,7 +179,7 @@ func registerAddCommandFlags(cmd *cobra.Command) {
 	cmd.Flags().BoolP("force", "f", false, "Overwrite existing workflow files without confirmation")
 
 	// Add append flag to add command
-	cmd.Flags().String("append", "", "Append extra content to the end of agentic workflow on installation")
+	cmd.Flags().String("append", "", "Append extra content to the end of the agentic workflow on installation")
 
 	// Add no-gitattributes flag to add command
 	cmd.Flags().Bool("no-gitattributes", false, "Skip updating .gitattributes file")

diff --git a/pkg/cli/add_wizard_command.go b/pkg/cli/add_wizard_command.go
@@ -125,7 +125,7 @@ Note: To create a new workflow from scratch, use the 'new' command instead.`,
 	_ = cmd.Flags().MarkHidden("skip-secret")
 
 	// Add append flag (matches --append in add command)
-	cmd.Flags().String("append", "", "Append extra content to the end of agentic workflow on installation")
+	cmd.Flags().String("append", "", "Append extra content to the end of the agentic workflow on installation")
 
 	// Add no-security-scanner flag (matches --no-security-scanner in add command)
 	cmd.Flags().Bool("no-security-scanner", false, "Skip security scanning of workflow markdown content")

diff --git a/pkg/cli/deploy_command.go b/pkg/cli/deploy_command.go
@@ -94,7 +94,7 @@ func registerDeployFlags(cmd *cobra.Command) {
 	cmd.Flags().StringP("name", "n", "", "Specify name for the added workflow (without .md extension)")
 	addEngineFlag(cmd)
 	cmd.Flags().BoolP("force", "f", false, "Overwrite existing workflow files without confirmation")
-	cmd.Flags().String("append", "", "Append extra content to the end of agentic workflow on installation")
+	cmd.Flags().String("append", "", "Append extra content to the end of the agentic workflow on installation")
 	cmd.Flags().Bool("no-gitattributes", false, "Skip updating .gitattributes file")
 	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")

diff --git a/pkg/cli/env_command.go b/pkg/cli/env_command.go
@@ -114,7 +114,7 @@ func NewEnvCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "env",
 		Short: "Manage compiler defaults as GitHub variables",
-		Long: `Manage compiler default variables in batch for repository, organization, or enterprise scope.
+		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).
 Set a field to null (or omit it) in update mode to delete the variable from the selected scope.

diff --git a/pkg/cli/flags.go b/pkg/cli/flags.go
@@ -14,11 +14,10 @@ func addEngineFlag(cmd *cobra.Command) {
 	cmd.Flags().StringP("engine", "e", "", engineFlagUsage("Override AI engine"))
 }
 
-// addEngineFilterFlag adds the --engine flag to a command for filtering.
-// This flag allows filtering results by AI engine type. No shorthand is
-// registered to avoid collision with the override-style --engine/-e flag.
+// 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().String("engine", "", engineFlagUsage("Filter logs by AI engine"))
+	cmd.Flags().StringP("engine", "e", "", engineFlagUsage("Filter logs by AI engine"))
 }
 
 // addRepoFlag adds the --repo/-r flag to a command.

diff --git a/pkg/cli/flags_test.go b/pkg/cli/flags_test.go
@@ -192,12 +192,12 @@ func TestShortFlagConsistency(t *testing.T) {
 			description:  "disable should have repo short flag",
 		},
 		{
-			name:         "logs command does not have -e for --engine",
+			name:         "logs command has -e for --engine",
 			shortFlag:    "e",
 			longFlag:     "engine",
 			commandSetup: func() *cobra.Command { return NewLogsCommand() },
-			shouldExist:  false,
-			description:  "logs should not have engine short flag",
+			shouldExist:  true,
+			description:  "logs should have engine short flag",
 		},
 
 		// -w flag (watch)

diff --git a/pkg/cli/forecast_command.go b/pkg/cli/forecast_command.go
@@ -108,7 +108,7 @@ Backtesting (--eval):
 	cmd.Flags().String("period", "month", "Aggregation period for projections: week or month")
 	cmd.Flags().Int("sample", 100, "Maximum number of completed runs to sample per workflow")
 	cmd.Flags().Bool("eval", false, "Evaluate forecast quality against past data (backtesting mode)")
-	cmd.Flags().Int("timeout", 0, "Gracefully stop forecast computation after this many minutes (0 disables timeout)")
+	cmd.Flags().Int("timeout", 0, "Gracefully stop forecast computation after this many minutes (0 = no timeout)")
 	addRepoFlag(cmd)
 	addJSONFlag(cmd)
 

diff --git a/pkg/cli/forecast_test.go b/pkg/cli/forecast_test.go
@@ -114,7 +114,7 @@ func TestNewForecastCommand_TimeoutFlag(t *testing.T) {
 
 	timeoutFlag := cmd.Flags().Lookup("timeout")
 	require.NotNil(t, timeoutFlag, "forecast command should register --timeout")
-	assert.Equal(t, "Gracefully stop forecast computation after this many minutes (0 disables timeout)", timeoutFlag.Usage)
+	assert.Equal(t, "Gracefully stop forecast computation after this many minutes (0 = no timeout)", timeoutFlag.Usage)
 	assert.Equal(t, "0", timeoutFlag.DefValue)
 }
 

diff --git a/pkg/cli/health_command.go b/pkg/cli/health_command.go
@@ -37,7 +37,7 @@ func NewHealthCommand() *cobra.Command {
 		Long: `Display workflow health metrics, success rates, and execution trends.
 
 Shows health metrics for workflows including:
-- Success/failure rates over time period
+- Success/failure rates over a time period
 - Trend indicators (↑ improving, → stable, ↓ degrading)
 - Average execution duration
 - Warnings when success rate drops below threshold

diff --git a/pkg/cli/init_command.go b/pkg/cli/init_command.go
@@ -29,7 +29,7 @@ This command:
 - Creates the custom agent at .github/agents/agentic-workflows.md
 - Removes old prompt files from .github/prompts/ if they exist
 - Configures VSCode settings (.vscode/settings.json)
-- Generates/updates .github/workflows/agentics-maintenance.yml if any workflows use expires field for discussions or issues
+- Generates/updates .github/workflows/agentics-maintenance.yml if any workflows use the expires field for discussions or issues
 
 By default (without --no-mcp):
 - Creates .github/workflows/copilot-setup-steps.yml with gh-aw installation steps
@@ -142,7 +142,7 @@ After running this command, you can:
 	cmd.Flags().Bool("no-mcp", false, "Skip configuring gh-aw MCP server integration for GitHub Copilot Agent")
 	cmd.Flags().Bool("no-skill", false, "Skip creating the agentic-workflows dispatcher skill")
 	cmd.Flags().Bool("no-agent", false, "Skip creating the Agentic Workflows custom agent")
-	cmd.Flags().String("codespaces", "", "Create devcontainer.json for GitHub Codespaces with agentic workflows support. Specify comma-separated repository names in the same organization (e.g., repo1,repo2), or use with an empty value for the current repo only")
+	cmd.Flags().String("codespaces", "", "Create devcontainer.json for GitHub Codespaces with agentic workflow support. Specify comma-separated repository names in the same organization (e.g., repo1,repo2), or use with an empty value for the current repo only")
 	cmd.Flags().Bool("completions", false, "Install shell completion for the detected shell (bash, zsh, fish, or PowerShell)")
 	cmd.Flags().Bool("create-pull-request", false, "Create a pull request with the initialization changes")
 	cmd.Flags().Bool("pr", false, "Alias for --create-pull-request")

diff --git a/pkg/cli/logs_command.go b/pkg/cli/logs_command.go
@@ -39,7 +39,7 @@ This command fetches workflow runs, downloads their artifacts, and extracts them
 organized folders named by run ID. It also provides an overview table with aggregate
 metrics including duration, token usage, and cost information.
 
-By default only the compact usage artifact is downloaded (token usage, run metadata).
+By default, only the compact usage artifact is downloaded (token usage, run metadata).
 Use --artifacts all to download all artifacts, or specify individual sets such as
 --artifacts agent,firewall to fetch only what you need.
 
@@ -83,7 +83,7 @@ Downloaded artifacts include (when using --artifacts all):
   ` + string(constants.CLIExtensionPrefix) + ` logs --ref main                # Filter logs by branch or tag
   ` + string(constants.CLIExtensionPrefix) + ` logs --ref feature-xyz         # Filter logs by feature branch
   ` + string(constants.CLIExtensionPrefix) + ` logs --filtered-integrity      # Filter logs containing items that were filtered by gateway integrity checks
-  ` + string(constants.CLIExtensionPrefix) + ` logs --no-staged               # Exclude staged workflow runs from results
+  ` + string(constants.CLIExtensionPrefix) + ` logs --exclude-staged          # Exclude staged workflow runs from results
 
   # Run ID range filtering
   ` + string(constants.CLIExtensionPrefix) + ` logs --after-run-id 1000       # Filter runs after run ID 1000
@@ -143,7 +143,7 @@ Downloaded artifacts include (when using --artifacts all):
 				repoOverride, _ := cmd.Flags().GetString("repo")
 				verbose, _ := cmd.Flags().GetBool("verbose")
 				toolGraph, _ := cmd.Flags().GetBool("tool-graph")
-				noStaged, _ := cmd.Flags().GetBool("no-staged")
+				noStaged, _ := cmd.Flags().GetBool("exclude-staged")
 				firewallOnly, _ := cmd.Flags().GetBool("firewall")
 				noFirewall, _ := cmd.Flags().GetBool("no-firewall")
 				parse, _ := cmd.Flags().GetBool("parse")
@@ -263,7 +263,7 @@ Downloaded artifacts include (when using --artifacts all):
 			afterRunID, _ := cmd.Flags().GetInt64("after-run-id")
 			verbose, _ := cmd.Flags().GetBool("verbose")
 			toolGraph, _ := cmd.Flags().GetBool("tool-graph")
-			noStaged, _ := cmd.Flags().GetBool("no-staged")
+			noStaged, _ := cmd.Flags().GetBool("exclude-staged")
 			firewallOnly, _ := cmd.Flags().GetBool("firewall")
 			noFirewall, _ := cmd.Flags().GetBool("no-firewall")
 			parse, _ := cmd.Flags().GetBool("parse")
@@ -363,7 +363,7 @@ Downloaded artifacts include (when using --artifacts all):
 	logsCmd.Flags().Int64("after-run-id", 0, "Filter runs with database ID after this value (exclusive)")
 	addRepoFlag(logsCmd)
 	logsCmd.Flags().Bool("tool-graph", false, "Generate Mermaid tool sequence graph from agent logs")
-	logsCmd.Flags().Bool("no-staged", false, "Exclude workflow runs that executed in staged mode (safe outputs previewed but not applied)")
+	logsCmd.Flags().Bool("exclude-staged", false, "Exclude workflow runs that executed in staged mode (safe outputs previewed but not applied)")
 	logsCmd.Flags().Bool("firewall", false, "Filter to only runs with firewall enabled")
 	logsCmd.Flags().Bool("no-firewall", false, "Filter to only runs without firewall enabled")
 	logsCmd.Flags().String("safe-output", "", "Filter to runs containing a specific safe output type (e.g., create-issue, missing-tool, missing-data, noop, report-incomplete)")

diff --git a/pkg/cli/logs_command_test.go b/pkg/cli/logs_command_test.go
@@ -40,7 +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")
+	assert.Equal(t, "e", engineFlag.Shorthand, "Engine filter flag should have shorthand '-e'")
 
 	// Check firewall flags
 	firewallFlag := flags.Lookup("firewall")

diff --git a/pkg/cli/logs_filtering_test.go b/pkg/cli/logs_filtering_test.go
@@ -74,10 +74,9 @@ func TestLogsCommandFlags(t *testing.T) {
 		t.Errorf("Expected engine flag default value to be empty, got: %s", engineFlag.DefValue)
 	}
 
-	// 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)
+	// Engine filter flag now has -e shorthand for consistency with other commands.
+	if engineFlag.Shorthand != "e" {
+		t.Errorf("Expected engine flag shorthand to be 'e', got: %s", engineFlag.Shorthand)
 	}
 }
 

diff --git a/pkg/cli/logs_orchestrator_filters.go b/pkg/cli/logs_orchestrator_filters.go
@@ -63,16 +63,16 @@ func applyRunFilters(result DownloadResult, opts runFilterOpts, verbose bool) bo
 		}
 	}
 
-	// Apply staged filtering if --no-staged flag is specified.
+	// Apply staged filtering if --exclude-staged flag is specified.
 	if opts.noStaged {
 		var isStaged bool
 		if awInfoErr == nil && awInfo != nil {
 			isStaged = awInfo.Staged
 		}
 		if isStaged {
-			logsOrchestratorLog.Printf("Skipping run %d: staged workflow filtered by --no-staged", result.Run.DatabaseID)
+			logsOrchestratorLog.Printf("Skipping run %d: staged workflow filtered by --exclude-staged", result.Run.DatabaseID)
 			if verbose {
-				fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Skipping run %d: workflow is staged (filtered out by --no-staged)", result.Run.DatabaseID)))
+				fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Skipping run %d: workflow is staged (filtered out by --exclude-staged)", result.Run.DatabaseID)))
 			}
 			return true
 		}

diff --git a/pkg/cli/logs_orchestrator_filters_test.go b/pkg/cli/logs_orchestrator_filters_test.go
@@ -79,7 +79,7 @@ func TestApplyRunFilters_Engine(t *testing.T) {
 	}
 }
 
-// TestApplyRunFilters_NoStaged verifies that --no-staged skips staged runs.
+// TestApplyRunFilters_NoStaged verifies that --exclude-staged skips staged runs.
 func TestApplyRunFilters_NoStaged(t *testing.T) {
 	tests := []struct {
 		name     string

diff --git a/pkg/cli/mcp.go b/pkg/cli/mcp.go
@@ -27,7 +27,7 @@ Available subcommands:
   - inspect    - Inspect MCP servers and list available tools, resources, and roots
   - add        - Add an MCP server to an agentic workflow`,
 		Example: `  gh aw mcp list                              # List all workflows with MCP servers
-  gh aw mcp inspect weekly-research           # Inspect MCP servers in workflow
+  gh aw mcp inspect weekly-research           # Inspect MCP servers in a workflow
   gh aw mcp add my-workflow tavily            # Add Tavily MCP server to workflow
   gh aw mcp inspect weekly-research --server github --tool create_issue  # Inspect specific tool`,
 		Args: func(cmd *cobra.Command, args []string) error {

diff --git a/pkg/cli/pr_command.go b/pkg/cli/pr_command.go
@@ -45,7 +45,7 @@ func NewPRCommand() *cobra.Command {
 		Long: `Pull request management utilities for transferring PRs between repositories.
 
 This command provides a tool for transferring pull requests from one repository
-to another, including the code changes, title, and body. Useful for
+to another, including the code changes, title, and body. This is useful for
 migrating work from trial repositories to production repositories.
 
 Available subcommands: