Standardize CLI flag descriptions across commands

cmd/gh-aw/main.go

@@ -432,14 +432,14 @@ Use "` + constants.CLIExtensionPrefix + ` help all" to show help for all command
 	initCmd := cli.NewInitCommand()
 
 	// Add flags to new command
-	newCmd.Flags().Bool("force", false, "Overwrite existing workflow files")
+	newCmd.Flags().Bool("force", false, "Overwrite existing files without confirmation")
 	newCmd.Flags().BoolP("interactive", "i", false, "Launch interactive workflow creation wizard")
 
 	// Add AI flag to compile and add commands
 	compileCmd.Flags().StringP("engine", "e", "", "Override AI engine (claude, codex, copilot, custom)")
 	compileCmd.Flags().Bool("validate", false, "Enable GitHub Actions workflow schema validation, container image validation, and action SHA validation")
 	compileCmd.Flags().BoolP("watch", "w", false, "Watch for changes to workflow files and recompile automatically")
-	compileCmd.Flags().String("dir", "", "Relative directory containing workflows (default: .github/workflows)")
+	compileCmd.Flags().String("dir", "", "Workflow directory (default: .github/workflows)")
 	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")
@@ -448,26 +448,26 @@ Use "` + constants.CLIExtensionPrefix + ` help all" to show help for all command
 	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().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 files (e.g., dependabot.yml)")
+	compileCmd.Flags().Bool("force", 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("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")
-	compileCmd.Flags().Bool("json", false, "Output validation results as JSON")
+	compileCmd.Flags().Bool("json", false, "Output results in JSON format")
 	rootCmd.AddCommand(compileCmd)
 
 	// Add flags to remove command
 	removeCmd.Flags().Bool("keep-orphans", false, "Skip removal of orphaned include files that are no longer referenced by any workflow")
 
 	// Add flags to enable/disable commands
-	enableCmd.Flags().StringP("repo", "r", "", "Repository to enable workflows in (owner/repo format)")
-	disableCmd.Flags().StringP("repo", "r", "", "Repository to disable workflows in (owner/repo format)")
+	enableCmd.Flags().StringP("repo", "r", "", "Target repository (owner/repo format)")
+	disableCmd.Flags().StringP("repo", "r", "", "Target repository (owner/repo format)")
 
 	// Add flags to run command
 	runCmd.Flags().Int("repeat", 0, "Number of times to repeat running workflows (0 = run once)")
 	runCmd.Flags().Bool("enable-if-needed", false, "Enable the workflow before running if needed, and restore state afterward")
 	runCmd.Flags().StringP("engine", "e", "", "Override AI engine (claude, codex, copilot, custom)")
-	runCmd.Flags().StringP("repo", "r", "", "Repository to run the workflow in (owner/repo format)")
+	runCmd.Flags().StringP("repo", "r", "", "Target repository (owner/repo format)")
 	runCmd.Flags().Bool("auto-merge-prs", false, "Auto-merge any pull requests created during the workflow execution")
 	runCmd.Flags().Bool("use-local-secrets", false, "Use local environment API key secrets for workflow execution (pushes and cleans up secrets in repository)")
 

pkg/cli/add_command.go

@@ -93,13 +93,13 @@ Note: To create a new workflow from scratch, use the 'new' command instead.`,
 	cmd.Flags().StringP("engine", "e", "", "Override AI engine (claude, codex, copilot, custom)")
 
 	// Add repository flag to add command
-	cmd.Flags().StringP("repo", "r", "", "Install and use workflows from specified repository (org/repo)")
+	cmd.Flags().StringP("repo", "r", "", "Source repository containing workflows (owner/repo format)")
 
 	// Add PR flag to add command
 	cmd.Flags().Bool("pr", false, "Create a pull request with the workflow changes")
 
 	// Add force flag to add command
-	cmd.Flags().Bool("force", false, "Overwrite existing workflow files")
+	cmd.Flags().Bool("force", false, "Overwrite existing files without confirmation")
 
 	// Add append flag to add command
 	cmd.Flags().String("append", "", "Append extra content to the end of agentic workflow on installation")
@@ -108,13 +108,13 @@ Note: To create a new workflow from scratch, use the 'new' command instead.`,
 	cmd.Flags().Bool("no-gitattributes", false, "Skip updating .gitattributes file")
 
 	// Add workflow directory flag to add command
-	cmd.Flags().StringP("dir", "d", "", "Specify subdirectory under .github/workflows/ (e.g., 'shared' for .github/workflows/shared/)")
+	cmd.Flags().StringP("dir", "d", "", "Subdirectory under .github/workflows/ (e.g., 'shared' creates .github/workflows/shared/)")
 
 	// Add no-stop-after flag to add command
-	cmd.Flags().Bool("no-stop-after", false, "Remove any stop-after field from the added workflow")
+	cmd.Flags().Bool("no-stop-after", false, "Remove any stop-after field from the workflow")
 
 	// Add stop-after flag to add command
-	cmd.Flags().String("stop-after", "", "Override stop-after value in the added workflow (e.g., '+48h', '2025-12-31 23:59:59')")
+	cmd.Flags().String("stop-after", "", "Override stop-after value in the workflow (e.g., '+48h', '2025-12-31 23:59:59')")
 
 	return cmd
 }

pkg/cli/audit.go

@@ -77,7 +77,7 @@ Examples:
 
 	// Add flags to audit command
 	auditCmd.Flags().StringP("output", "o", "./logs", "Output directory for downloaded logs and artifacts")
-	auditCmd.Flags().Bool("json", false, "Output audit report as JSON instead of formatted console tables")
+	auditCmd.Flags().Bool("json", false, "Output results in JSON format")
 	auditCmd.Flags().Bool("parse", false, "Run JavaScript parsers on agent logs and firewall logs, writing markdown to log.md and firewall.md")
 
 	return auditCmd

pkg/cli/logs.go

@@ -452,18 +452,18 @@ Examples:
 	logsCmd.Flags().String("start-date", "", "Filter runs created after this date (YYYY-MM-DD or delta like -1d, -1w, -1mo)")
 	logsCmd.Flags().String("end-date", "", "Filter runs created before this date (YYYY-MM-DD or delta like -1d, -1w, -1mo)")
 	logsCmd.Flags().StringP("output", "o", "./logs", "Output directory for downloaded logs and artifacts")
-	logsCmd.Flags().StringP("engine", "e", "", "Filter logs by agentic engine type (claude, codex, copilot)")
+	logsCmd.Flags().StringP("engine", "e", "", "Filter logs by engine type (claude, codex, copilot)")
 	logsCmd.Flags().String("branch", "", "Filter runs by branch name (e.g., main, feature-branch)")
 	logsCmd.Flags().Int64("before-run-id", 0, "Filter runs with database ID before this value (exclusive)")
 	logsCmd.Flags().Int64("after-run-id", 0, "Filter runs with database ID after this value (exclusive)")
-	logsCmd.Flags().StringP("repo", "r", "", "Repository to download logs from (owner/repo format)")
+	logsCmd.Flags().StringP("repo", "r", "", "Target repository (owner/repo format)")
 	logsCmd.Flags().Bool("tool-graph", false, "Generate Mermaid tool sequence graph from agent logs")
 	logsCmd.Flags().Bool("no-staged", false, "Filter out staged workflow runs (exclude runs with staged: true in aw_info.json)")
 	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().Bool("parse", false, "Run JavaScript parsers on agent logs and firewall logs, writing markdown to log.md and firewall.md")
-	logsCmd.Flags().Bool("json", false, "Output logs data as JSON instead of formatted console tables")
-	logsCmd.Flags().Int("timeout", 0, "Maximum time in seconds to spend downloading logs (0 = no timeout)")
+	logsCmd.Flags().Bool("json", false, "Output results in JSON format")
+	logsCmd.Flags().Int("timeout", 0, "Download timeout in seconds (0 = no timeout)")
 
 	return logsCmd
 }

pkg/cli/logs_test.go

@@ -987,7 +987,7 @@ func TestLogsCommandFlags(t *testing.T) {
 		t.Fatal("Engine flag not found")
 	}
 
-	if engineFlag.Usage != "Filter logs by agentic engine type (claude, codex, copilot)" {
+	if engineFlag.Usage != "Filter logs by engine type (claude, codex, copilot)" {
 		t.Errorf("Unexpected engine flag usage text: %s", engineFlag.Usage)
 	}
 

pkg/cli/status.go

@@ -27,7 +27,7 @@ func NewStatusCommand() *cobra.Command {
 		},
 	}
 
-	cmd.Flags().Bool("json", false, "Output status in JSON format")
+	cmd.Flags().Bool("json", false, "Output results in JSON format")
 
 	return cmd
 }

pkg/cli/trial_command.go

@@ -156,10 +156,10 @@ Trial results are saved both locally (in trials/ directory) and in the host repo
 	cmd.Flags().Bool("delete-host-repo-after", false, "Delete the host repository after completion (default: keep)")
 	cmd.Flags().Bool("force-delete-host-repo-before", false, "Force delete the host repository before creation, if it exists before creating it")
 	cmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompts")
-	cmd.Flags().Int("timeout", 30, "Timeout in minutes for workflow execution (default: 30)")
+	cmd.Flags().Int("timeout", 30, "Execution timeout in minutes (default: 30)")
 	cmd.Flags().String("trigger-context", "", "Trigger context URL (e.g., GitHub issue URL) for issue-triggered workflows")
 	cmd.Flags().Int("repeat", 0, "Number of times to repeat running workflows (0 = run once)")
-	cmd.Flags().Bool("auto-merge-prs", false, "Auto-merge any pull requests created during the trial (requires --clone-repo)")
+	cmd.Flags().Bool("auto-merge-prs", false, "Auto-merge any pull requests created during trial execution")
 	cmd.Flags().StringP("engine", "e", "", "Override AI engine (claude, codex, copilot, custom)")
 	cmd.Flags().String("append", "", "Append extra content to the end of agentic workflow on installation")
 	cmd.Flags().Bool("use-local-secrets", false, "Use local environment API key secrets for trial execution (pushes and cleans up secrets in repository)")

pkg/cli/update_command.go

@@ -76,12 +76,12 @@ Examples:
 	}
 
 	cmd.Flags().Bool("major", false, "Allow major version updates when updating tagged releases")
-	cmd.Flags().Bool("force", false, "Force update even if no changes detected")
+	cmd.Flags().Bool("force", false, "Force update even if no changes are detected")
 	cmd.Flags().StringP("engine", "e", "", "Override AI engine (claude, codex, copilot, custom)")
 	cmd.Flags().Bool("pr", false, "Create a pull request with the workflow changes")
-	cmd.Flags().String("dir", "", "Relative directory containing workflows (default: .github/workflows)")
-	cmd.Flags().Bool("no-stop-after", false, "Remove any stop-after field from the updated workflow")
-	cmd.Flags().String("stop-after", "", "Override stop-after value in the updated workflow (e.g., '+48h', '2025-12-31 23:59:59')")
+	cmd.Flags().String("dir", "", "Workflow directory (default: .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("merge", false, "Merge local changes with upstream updates instead of overriding")
 
 	return cmd