Unify gh aw help/docs wording and expose experiments command in CLI reference

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)

pkg/cli/forecast_command.go

@@ -66,7 +66,7 @@ Backtesting (--eval):
 ` + WorkflowIDExplanation,
 		Example: `  ` + string(constants.CLIExtensionPrefix) + ` forecast                        # Forecast all workflows (monthly)
   ` + string(constants.CLIExtensionPrefix) + ` forecast ci-doctor              # Forecast a specific workflow
-  ` + string(constants.CLIExtensionPrefix) + ` forecast ci-doctor daily-planner # Compare two workflows
+  ` + string(constants.CLIExtensionPrefix) + ` forecast ci-doctor daily-news    # Compare two workflows
   ` + string(constants.CLIExtensionPrefix) + ` forecast --period week           # Weekly projections
   ` + string(constants.CLIExtensionPrefix) + ` forecast --days 7               # Use 7-day history window
   ` + string(constants.CLIExtensionPrefix) + ` forecast --sample 50            # Sample up to 50 runs per workflow

pkg/cli/lint_command.go

@@ -39,10 +39,10 @@ func NewLintCommand() *cobra.Command {
 
 This command does not recompile Markdown workflows and does not run zizmor or poutine.
 By default, shellcheck and pyflakes integrations are disabled for generated run scripts.`,
-		Example: `  ` + string(constants.CLIExtensionPrefix) + ` lint
-  ` + string(constants.CLIExtensionPrefix) + ` lint .github/workflows/foo.lock.yml
-  ` + string(constants.CLIExtensionPrefix) + ` lint --dir .github/workflows
-  ` + string(constants.CLIExtensionPrefix) + ` lint --shellcheck --pyflakes`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` lint                                  # Lint all .lock.yml workflows in the default directory
+  ` + string(constants.CLIExtensionPrefix) + ` lint .github/workflows/foo.lock.yml    # Lint a specific lock file
+  ` + string(constants.CLIExtensionPrefix) + ` lint --dir custom-workflows/            # Lint all lock files in a custom directory
+  ` + string(constants.CLIExtensionPrefix) + ` lint --shellcheck --pyflakes            # Enable actionlint script integrations`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			workflowDir, _ := cmd.Flags().GetString("dir")
 			includeShellcheck, _ := cmd.Flags().GetBool("shellcheck")

pkg/cli/logs_command.go

@@ -54,20 +54,20 @@ Downloaded artifacts include (when using --artifacts all):
 - aw-{branch}.patch: Git patch of changes for each branch (one file per PR/push)
 - workflow-logs/: GitHub Actions workflow run logs (job logs organized in subdirectory)
 - summary.json: Complete metrics and run data for all downloaded runs
-`, validArtifactSets) + WorkflowIDExplanation,
+`, validArtifactSets) + "\n\n" + WorkflowIDExplanation,
 		Example: `  # Basic usage
   ` + string(constants.CLIExtensionPrefix) + ` logs                           # Download logs for all workflows
   ` + string(constants.CLIExtensionPrefix) + ` logs weekly-research           # Download logs for specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` logs weekly-research.md        # Download logs (alternative format)
   ` + string(constants.CLIExtensionPrefix) + ` logs -c 10                     # Download last 10 matching runs
 
   # Date filtering
-  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date 2024-01-01   # Download all runs after date
-  ` + string(constants.CLIExtensionPrefix) + ` logs --end-date 2024-01-31     # Download all runs before date
+  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date 2024-01-01   # Download up to 10 runs after date
+  ` + string(constants.CLIExtensionPrefix) + ` logs --end-date 2024-01-31     # Download up to 10 runs before date
   ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1w          # Download up to 10 runs from last week
   ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1w -c 5     # Download up to 5 runs from last week
-  ` + string(constants.CLIExtensionPrefix) + ` logs --end-date -1d            # Download all runs until yesterday
-  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1mo         # Download all runs from last month
+  ` + string(constants.CLIExtensionPrefix) + ` logs --end-date -1d            # Download up to 10 runs before yesterday
+  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1mo         # Download up to 10 runs from last month
 
   # Content filtering
   ` + string(constants.CLIExtensionPrefix) + ` logs --engine claude           # Filter logs by claude engine
@@ -375,7 +375,7 @@ Downloaded artifacts include (when using --artifacts all):
 	logsCmd.Flags().Bool("train", false, "Analyze log patterns across downloaded runs and save pattern weights to drain3_weights.json in the output directory")
 	logsCmd.Flags().String("format", "", "Output format: console (decorated tables), tsv (tab-separated), pretty (cross-run report), markdown (cross-run Markdown). Default: compact agent-optimized output")
 	logsCmd.Flags().String("report-file", "", "Write --format markdown output directly to this file path instead of stdout (creates parent directories as needed)")
-	logsCmd.Flags().Int("last", 0, "Alias for --count: number of recent runs to download")
+	logsCmd.Flags().Int("last", 0, "Alias for --count/-c: number of recent runs to download")
 	logsCmd.Flags().StringSlice("artifacts", []string{"usage"}, "Artifact sets to download (default: usage — compact summary for faster downloads). Use 'all' for everything, or comma-separate sets. Valid sets: "+validArtifactSets)
 	logsCmd.Flags().String("cache-before", "", "(Cache eviction) Evict locally cached run folders for runs before this date, prior to downloading. Accepts deltas like -1d, -1w, -1mo (or explicit day counts like -30d), or an absolute date YYYY-MM-DD. Unlike --start-date, this only clears local cache and does not filter which runs are fetched.")
 	logsCmd.Flags().String("after", "", "Alias for --cache-before")

pkg/cli/logs_command_test.go

@@ -62,6 +62,9 @@ func TestNewLogsCommand(t *testing.T) {
 	assert.NotNil(t, afterRunIDFlag, "Should have 'after-run-id' flag")
 	beforeRunIDFlag := flags.Lookup("before-run-id")
 	assert.NotNil(t, beforeRunIDFlag, "Should have 'before-run-id' flag")
+	lastFlag := flags.Lookup("last")
+	assert.NotNil(t, lastFlag, "Should have 'last' flag")
+	assert.Contains(t, lastFlag.Usage, "--count/-c", "--last usage should mention the canonical --count/-c flag")
 
 	// Check tool-graph flag
 	toolGraphFlag := flags.Lookup("tool-graph")

pkg/cli/trial_command.go

@@ -15,7 +15,7 @@ func NewTrialCommand(validateEngine func(string) error) *cobra.Command {
 		Long: `Run one or more agentic workflows in trial mode against a simulated repository.
 
 This command creates a temporary private repository in your GitHub account, installs the specified
-workflow(s) from their source repositories, and runs them in "trial mode" to capture safe outputs without
+workflows from their source repositories, and runs them in "trial mode" to capture safe outputs without
 making actual changes to the "simulated" host repository.
 
 Repository modes:
@@ -114,16 +114,16 @@ 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 (kept by default)")
 	cmd.Flags().Bool("force-delete-host-repo-before", false, "Force delete the host repository before creation if it already exists")
 	cmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompts")
-	cmd.Flags().Bool("dry-run", false, "Preview trial execution without applying any changes")
+	cmd.Flags().Bool("dry-run", false, "Preview trial execution without creating repos or running workflows")
 	cmd.Flags().Int("timeout", 30, "Execution timeout in minutes (set to 0 to disable timeout)")
 	cmd.Flags().String("trigger-context", "", "Trigger context URL (e.g., GitHub issue URL) for issue-triggered workflows")
 	cmd.Flags().Int("repeat", 0, "Number of additional times to run after the initial execution (e.g., --repeat 3 runs 4 times total)")
 	cmd.Flags().Bool("auto-merge-prs", false, "Auto-merge any pull requests created during trial execution")
 	addEngineFlag(cmd)
 	addJSONFlag(cmd)
 	cmd.Flags().String("append", "", "Append extra content to the end of agentic workflow on installation")
-	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.MarkFlagsMutuallyExclusive("logical-repo", "clone-repo")