fix(cli): address 7 CLI consistency issues across help text and flag behavior (#25658)

Author: Copilot

cmd/gh-aw/main.go

@@ -174,16 +174,18 @@ By default, this command also removes orphaned include files that are no longer
 by any workflow. Use --keep-orphans to skip this cleanup.
 
 Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` remove my-workflow       # Remove specific workflow
-  ` + string(constants.CLIExtensionPrefix) + ` remove test-             # Remove all workflows starting with 'test-'
-  ` + string(constants.CLIExtensionPrefix) + ` remove old- --keep-orphans  # Remove workflows but keep orphaned includes`,
+  ` + string(constants.CLIExtensionPrefix) + ` remove my-workflow              # Remove specific workflow
+  ` + string(constants.CLIExtensionPrefix) + ` remove test-                    # Remove all workflows starting with 'test-'
+  ` + string(constants.CLIExtensionPrefix) + ` remove old- --keep-orphans      # Remove workflows but keep orphaned includes
+  ` + string(constants.CLIExtensionPrefix) + ` remove my-workflow --dir .github/workflows/shared  # Remove from custom directory`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var pattern string
 		if len(args) > 0 {
 			pattern = args[0]
 		}
 		keepOrphans, _ := cmd.Flags().GetBool("keep-orphans")
-		return cli.RemoveWorkflows(pattern, keepOrphans)
+		workflowDir, _ := cmd.Flags().GetString("dir")
+		return cli.RemoveWorkflows(pattern, keepOrphans, workflowDir)
 	},
 }
 
@@ -367,7 +369,6 @@ This command accepts one or more workflow IDs.
 The workflows must have been added as actions and compiled.
 
 This command only works with workflows that have workflow_dispatch triggers.
-It executes 'gh workflow run <workflow-lock-file>' to trigger each workflow on GitHub Actions.
 
 ` + cli.WorkflowIDExplanation + `
 
@@ -705,8 +706,10 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 
 	// 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")
+	removeCmd.Flags().StringP("dir", "d", "", "Workflow directory (default: .github/workflows)")
 	// Register completions for remove command
 	removeCmd.ValidArgsFunction = cli.CompleteWorkflowNames
+	cli.RegisterDirFlagCompletion(removeCmd, "dir")
 
 	// Add flags to enable/disable commands
 	enableCmd.Flags().StringP("repo", "r", "", "Target repository ([HOST/]owner/repo format). Defaults to current repository")

pkg/cli/add_command.go

@@ -63,7 +63,7 @@ Examples:
   ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --create-pull-request --force
   ` + string(constants.CLIExtensionPrefix) + ` add ./my-workflow.md                             # Add local workflow
   ` + string(constants.CLIExtensionPrefix) + ` add ./*.md                                       # Add all local workflows
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --dir shared   # Add to .github/workflows/shared/
+  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --dir .github/workflows/shared   # Add to .github/workflows/shared/
 
 Workflow specifications:
   - Three parts: "owner/repo/workflow-name[@version]" (implicitly looks in workflows/ directory)
@@ -74,7 +74,7 @@ Workflow specifications:
   - Version can be tag, branch, or SHA (for remote workflows)
 
 The -n flag allows you to specify a custom name for the workflow file (only applies to the first workflow when adding multiple).
-The --dir flag allows you to specify a subdirectory under .github/workflows/ where the workflow will be added.
+The --dir flag allows you to specify the workflow directory (default: .github/workflows).
 The --create-pull-request flag creates a pull request with the workflow changes.
 The --force flag overwrites existing workflow files.
 
@@ -151,7 +151,7 @@ Note: For guided interactive setup, use the 'add-wizard' command instead.`,
 	cmd.Flags().Bool("no-gitattributes", false, "Skip updating .gitattributes file")
 
 	// Add workflow directory flag to add command
-	cmd.Flags().StringP("dir", "d", "", "Subdirectory under .github/workflows/ (e.g., 'shared' creates .github/workflows/shared/)")
+	cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: .github/workflows)")
 
 	// Add no-stop-after flag to add command
 	cmd.Flags().Bool("no-stop-after", false, "Remove any stop-after field from the workflow")
@@ -328,11 +328,7 @@ func addWorkflowWithTracking(resolved *ResolvedWorkflow, tracker *FileTracker, o
 			return fmt.Errorf("workflow directory must be a relative path, got: %s", opts.WorkflowDir)
 		}
 		opts.WorkflowDir = filepath.Clean(opts.WorkflowDir)
-		if !strings.HasPrefix(opts.WorkflowDir, ".github/workflows") {
-			githubWorkflowsDir = filepath.Join(gitRoot, ".github/workflows", opts.WorkflowDir)
-		} else {
-			githubWorkflowsDir = filepath.Join(gitRoot, opts.WorkflowDir)
-		}
+		githubWorkflowsDir = filepath.Join(gitRoot, opts.WorkflowDir)
 	} else {
 		githubWorkflowsDir = filepath.Join(gitRoot, ".github/workflows")
 	}

pkg/cli/add_integration_test.go

@@ -432,8 +432,8 @@ Test content.
 	err = os.WriteFile(localWorkflowPath, []byte(localWorkflowContent), 0644)
 	require.NoError(t, err, "should write local workflow file")
 
-	// Add to a custom directory
-	cmd := exec.Command(setup.binaryPath, "add", localWorkflowPath, "--dir", "experimental")
+	// Add to a custom directory (full path required, consistent with compile/fix/upgrade --dir)
+	cmd := exec.Command(setup.binaryPath, "add", localWorkflowPath, "--dir", ".github/workflows/experimental")
 	cmd.Dir = setup.tempDir
 	output, err := cmd.CombinedOutput()
 	outputStr := string(output)
@@ -442,7 +442,7 @@ Test content.
 
 	require.NoError(t, err, "add command should succeed: %s", outputStr)
 
-	// Verify the workflow file was created in the custom subdirectory
+	// Verify the workflow file was created in the custom directory
 	customDir := filepath.Join(setup.tempDir, ".github", "workflows", "experimental")
 	info, err := os.Stat(customDir)
 	require.NoError(t, err, "custom workflows subdirectory should exist")

pkg/cli/add_wizard_command.go

@@ -84,7 +84,7 @@ 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
-	cmd.Flags().StringP("dir", "d", "", "Subdirectory under .github/workflows/ (e.g., 'shared' creates .github/workflows/shared/)")
+	cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: .github/workflows)")
 
 	// Add no-stop-after flag
 	cmd.Flags().Bool("no-stop-after", false, "Remove any stop-after field from the workflow")

pkg/cli/commands_test.go

@@ -213,7 +213,7 @@ This is a test workflow to verify the --no-emit flag functionality.`
 }
 
 func TestRemoveWorkflows(t *testing.T) {
-	err := RemoveWorkflows("test-pattern", false)
+	err := RemoveWorkflows("test-pattern", false, "")
 
 	// Should not error since it's a stub implementation
 	if err != nil {
@@ -385,7 +385,7 @@ Test workflow for command existence.`
 			_, err := CompileWorkflows(context.Background(), config)
 			return err
 		}, false, "CompileWorkflows"},
-		{func() error { return RemoveWorkflows("nonexistent", false) }, false, "RemoveWorkflows"},                    // Should handle missing directory gracefully
+		{func() error { return RemoveWorkflows("nonexistent", false, "") }, false, "RemoveWorkflows"},                // Should handle missing directory gracefully
 		{func() error { return StatusWorkflows("nonexistent", false, false, "", "", "") }, false, "StatusWorkflows"}, // Should handle missing directory gracefully
 		{func() error {
 			return RunWorkflowOnGitHub(context.Background(), "", RunOptions{})

pkg/cli/mcp_add.go

@@ -315,7 +315,6 @@ This command searches the MCP registry for the specified server, adds it to the
 and automatically compiles the workflow. If the tool already exists, the command will fail.
 
 When called with no arguments, it will show a list of available MCP servers from the registry.
-When called with only a workflow argument, it will show an error asking for a server name.
 
 The workflow-id-or-file can be:
 - A workflow ID (basename without .md extension, e.g., "weekly-research")

pkg/cli/pr_command.go

@@ -77,8 +77,8 @@ and creates a new pull request in the target repository with the same title and
 The target repository defaults to the current repository unless --repo is specified.
 
 Examples:
-  gh aw pr transfer https://github.com/trial/repo/pull/234
-  gh aw pr transfer https://github.com/PR-OWNER/PR-REPO/pull/234 --repo owner/target-repo
+  gh aw pr transfer https://github.com/owner/repo/pull/234
+  gh aw pr transfer https://github.com/owner/repo/pull/234 --repo owner/target-repo
 
 The command will:
 1. Fetch the PR details (title, body, changes)

pkg/cli/remove_command.go

@@ -17,9 +17,12 @@ import (
 var removeLog = logger.New("cli:remove_command")
 
 // RemoveWorkflows removes workflows matching a pattern
-func RemoveWorkflows(pattern string, keepOrphans bool) error {
-	removeLog.Printf("Removing workflows: pattern=%q, keepOrphans=%v", pattern, keepOrphans)
-	workflowsDir := getWorkflowsDir()
+func RemoveWorkflows(pattern string, keepOrphans bool, workflowDir string) error {
+	removeLog.Printf("Removing workflows: pattern=%q, keepOrphans=%v, workflowDir=%q", pattern, keepOrphans, workflowDir)
+	workflowsDir := workflowDir
+	if workflowsDir == "" {
+		workflowsDir = getWorkflowsDir()
+	}
 
 	if _, err := os.Stat(workflowsDir); os.IsNotExist(err) {
 		fmt.Fprintln(os.Stderr, console.FormatInfoMessage("No .github/workflows directory found."))

pkg/cli/trial_command.go

@@ -12,7 +12,7 @@ func NewTrialCommand(validateEngine func(string) error) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "trial <workflow-spec>...",
 		Short: "Run one or more agentic workflows in trial mode against a simulated repository",
-		Long: `Trial one or more agentic workflows as if they were running in a repository.
+		Long: `Run one or more agentic workflows in trial mode as if they were running in a repository.
 
 This command creates a temporary private repository in your GitHub space, installs the specified
 workflow(s) from their source repositories, and runs them in "trial mode" to capture safe outputs without

pkg/cli/upgrade_command.go

@@ -109,7 +109,7 @@ Examples:
 	}
 
 	cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: .github/workflows)")
-	cmd.Flags().Bool("no-fix", false, "Only update agent files (skips codemods, action version updates, and workflow compilation)")
+	cmd.Flags().Bool("no-fix", false, "Skip codemods, action version updates, and workflow compilation (only update agent files)")
 	cmd.Flags().Bool("no-actions", false, "Skip updating GitHub Actions versions")
 	cmd.Flags().Bool("no-compile", false, "Skip recompiling workflows (do not modify lock files)")
 	cmd.Flags().Bool("create-pull-request", false, "Create a pull request with the upgrade changes")