Unify gh aw help/docs wording and expose experiments command in CLI reference (#44794)

* Initial plan

* Harmonize CLI help wording and docs examples

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Refine remaining CLI consistency wording gaps

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Fix logs help trailing blank line and lint --dir example path

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

* fix: broaden trial --dry-run flag description per github-actions review

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Co-authored-by: Peli de Halleux <pelikhan@users.noreply.github.com>

Author: 3 people

cmd/gh-aw/main.go

@@ -276,7 +276,7 @@ Unlike 'upgrade', compilation only applies codemods when you opt in with --fix.
   ` + string(constants.CLIExtensionPrefix) + ` compile workflow.md        # Compile by file path
   ` + string(constants.CLIExtensionPrefix) + ` compile .github/workflows  # Compile all workflows in a directory
   ` + string(constants.CLIExtensionPrefix) + ` compile --dir custom/workflows  # Compile from custom directory
-  ` + string(constants.CLIExtensionPrefix) + ` compile --watch ci-doctor     # Watch and auto-compile
+  ` + string(constants.CLIExtensionPrefix) + ` compile ci-doctor --watch     # Watch and auto-compile
   ` + string(constants.CLIExtensionPrefix) + ` compile --trial --logical-repo owner/repo  # Compile for trial mode
   ` + string(constants.CLIExtensionPrefix) + ` compile --dependabot        # Generate Dependabot manifests
   ` + string(constants.CLIExtensionPrefix) + ` compile --dependabot --force  # Force overwrite existing dependabot.yml
@@ -433,7 +433,7 @@ This command only works with workflows that have workflow_dispatch triggers.
   gh aw run daily-perf-improver --auto-merge-prs  # Auto-merge any PRs created during execution
   gh aw run daily-perf-improver -F name=value -F env=prod  # Pass workflow inputs
   gh aw run daily-perf-improver --push  # Commit and push workflow files before running
-  gh aw run daily-perf-improver --dry-run  # Validate without actually running
+  gh aw run daily-perf-improver --dry-run  # Preview without triggering workflow runs
   gh aw run daily-perf-improver --json  # Output results in JSON format`,
 	Args: cobra.ArbitraryArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -795,7 +795,7 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	runCmd.Flags().Bool("auto-merge-prs", false, "Auto-merge any pull requests created during the workflow execution")
 	runCmd.Flags().StringArrayP("raw-field", "F", []string{}, "Add a string parameter in key=value format (can be used multiple times)")
 	runCmd.Flags().Bool("push", false, "Commit and push workflow files (including transitive imports) before running")
-	runCmd.Flags().Bool("dry-run", false, "Validate workflow without actually triggering execution on GitHub Actions")
+	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")
 	runCmd.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")
 	// Register completions for run command

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

@@ -383,6 +383,7 @@ gh aw run workflow1 workflow2               # Run multiple workflows
 gh aw run workflow --repeat 3               # Run 4 times total (1 initial + 3 repeats)
 gh aw run workflow --push                   # Auto-commit, push, and dispatch workflow
 gh aw run workflow --push --ref main        # Push to specific branch
+gh aw run workflow --dry-run                # Preview without triggering workflow runs
 gh aw run workflow --json                   # Output triggered workflow results as JSON
 ```
 
@@ -614,7 +615,7 @@ Forecast AI Credit (AIC) usage for agentic workflows using recent run history an
 ```bash wrap
 gh aw forecast                              # Forecast all workflows (monthly)
 gh aw forecast ci-doctor                    # Forecast a specific workflow
-gh aw forecast ci-doctor daily-planner      # Compare two workflows
+gh aw forecast ci-doctor daily-news         # Compare two workflows
 gh aw forecast --period week                # Weekly projections
 gh aw forecast --days 7                     # Use 7-day history window
 gh aw forecast --sample 50                  # Sample up to 50 runs per workflow

pkg/cli/add_command.go

@@ -98,7 +98,7 @@ type AddWorkflowsResult struct {
 func NewAddCommand(validateEngine func(string) error) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "add <workflow>...",
-		Short:   "Add agentic workflows from repositories or local files to .github/workflows",
+		Short:   "Add agentic workflows from repositories, local files, or URLs to .github/workflows",
 		Long:    addCommandLong,
 		Example: addCommandExample,
 		Args: func(cmd *cobra.Command, args []string) error {
@@ -194,8 +194,8 @@ func registerAddCommandFlags(cmd *cobra.Command) {
 	cmd.Flags().String("stop-after", "", "Override stop-after value in the workflow (e.g., '+48h', '2025-12-31 23:59:59')")
 
 	// Add no-security-scanner flag to add command (--disable-security-scanner is kept as a deprecated alias)
-	cmd.Flags().Bool("no-security-scanner", false, "Disable security scanning of workflow markdown content")
-	cmd.Flags().Bool("disable-security-scanner", false, "Disable security scanning of workflow markdown content")
+	cmd.Flags().Bool("no-security-scanner", false, "Skip security scanning of workflow markdown content")
+	cmd.Flags().Bool("disable-security-scanner", false, "Skip security scanning of workflow markdown content")
 	_ = cmd.Flags().MarkDeprecated("disable-security-scanner", "use --no-security-scanner instead")
 
 	// Register completions for add command

pkg/cli/add_command_test.go

@@ -27,7 +27,7 @@ func TestNewAddCommand(t *testing.T) {
 
 	require.NotNil(t, cmd, "NewAddCommand should not return nil")
 	assert.Equal(t, "add <workflow>...", cmd.Use, "Command use should be 'add <workflow>...'")
-	assert.Equal(t, "Add agentic workflows from repositories or local files to .github/workflows", cmd.Short, "Command short description should match")
+	assert.Equal(t, "Add agentic workflows from repositories, local files, or URLs to .github/workflows", cmd.Short, "Command short description should match")
 	assert.Contains(t, cmd.Long, "Add one or more agentic workflows", "Command long description should contain expected text")
 
 	// Verify Args validator is set

pkg/cli/add_wizard_command.go

@@ -128,7 +128,7 @@ Note: To create a new workflow from scratch, use the 'new' command instead.`,
 	cmd.Flags().String("append", "", "Append extra content to the end of agentic workflow on installation")
 
 	// Add no-security-scanner flag (matches --no-security-scanner in add command)
-	cmd.Flags().Bool("no-security-scanner", false, "Disable security scanning of workflow markdown content")
+	cmd.Flags().Bool("no-security-scanner", false, "Skip security scanning of workflow markdown content")
 
 	// Register completions
 	RegisterEngineFlagCompletion(cmd)

pkg/cli/deploy_command.go

@@ -90,7 +90,7 @@ func validateDeployArgs(cmd *cobra.Command, args []string) error {
 }
 
 func registerDeployFlags(cmd *cobra.Command) {
-	cmd.Flags().StringP("repo", "r", "", "Target repository in [HOST/]owner/repo format (required unless --org is provided)")
+	cmd.Flags().StringP("repo", "r", "", "Target repository ([HOST/]owner/repo format). Required unless --org is provided")
 	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")
@@ -99,8 +99,8 @@ func registerDeployFlags(cmd *cobra.Command) {
 	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-security-scanner", false, "Disable security scanning of workflow markdown content")
-	cmd.Flags().Bool("disable-security-scanner", false, "Disable security scanning of workflow markdown content")
+	cmd.Flags().Bool("no-security-scanner", false, "Skip security scanning of workflow markdown content")
+	cmd.Flags().Bool("disable-security-scanner", false, "Skip security scanning of workflow markdown content")
 	_ = cmd.Flags().MarkDeprecated("disable-security-scanner", "use --no-security-scanner instead")
 	cmd.Flags().String("cool-down", defaultDeployCooldown, coolDownFlagUsage)
 	cmd.Flags().String("org", "", "Deploy workflows across repositories in an organization")

pkg/cli/deploy_command_test.go

@@ -60,7 +60,7 @@ func TestNewDeployCommand_RegistersCoreFlags(t *testing.T) {
 
 	repoFlag := cmd.Flags().Lookup("repo")
 	require.NotNil(t, repoFlag, "expected --repo flag to be registered")
-	assert.Contains(t, repoFlag.Usage, "required unless --org is provided")
+	assert.Contains(t, repoFlag.Usage, "Required unless --org is provided")
 }
 
 func TestNewDeployCommand_CoolDownFlagUsageMatchesUpdate(t *testing.T) {

pkg/cli/experiments_command.go

@@ -88,9 +88,8 @@ type ExperimentsAnalyzeConfig struct {
 // NewExperimentsCommand creates the experiments command with its subcommands.
 func NewExperimentsCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:    "experiments",
-		Hidden: true,
-		Short:  "Explore ongoing experiments in the repository",
+		Use:   "experiments",
+		Short: "Explore ongoing experiments in the repository",
 		Long: `Explore ongoing experiments in the repository.
 
 Experiments are tracked via git branches with the "experiments/" prefix (e.g.,

pkg/cli/experiments_command_test.go

@@ -300,7 +300,7 @@ func TestNewExperimentsCommand(t *testing.T) {
 	cmd := NewExperimentsCommand()
 	require.NotNil(t, cmd, "command should be created")
 	assert.Equal(t, "experiments", cmd.Name(), "command name should be experiments")
-	assert.True(t, cmd.Hidden, "experiments command should be hidden")
+	assert.False(t, cmd.Hidden, "experiments command should be visible")
 
 	subCmds := cmd.Commands()
 	subNames := make([]string, 0, len(subCmds))

pkg/cli/fix_command.go

@@ -47,16 +47,16 @@ Use --list-codemods to see all available codemods and their descriptions.
 If no workflows are specified, all Markdown files in .github/workflows will be processed.
 
 The command will:
-  1. Scan workflow files for deprecated fields
-  2. Apply relevant codemods to fix issues
-  3. Report what was changed in each file
+  1. Scan workflow files for deprecated fields.
+  2. Apply relevant codemods to fix issues.
+  3. Report what was changed in each file.
 
 Without --write (dry-run mode), no files are modified. With --write, the command performs
 all steps and additionally:
-  4. Write updated files back to disk
-  5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists
-  6. Delete old template files from previous versions if present
-  7. Delete old workflow-specific .agent.md files from .github/agents/ if present
+  4. Write updated files back to disk.
+  5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists.
+  6. Delete old template files from previous versions if present.
+  7. Delete old workflow-specific .agent.md files from .github/agents/ if present.
 
 ` + WorkflowIDExplanation,
 		Example: `  ` + string(constants.CLIExtensionPrefix) + ` fix                     # Check all workflows (dry-run)