Skip to content

fix(cli): standardize --help flag descriptions and "agentic workflow" terminology #20375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Mar 10, 2026
Merged

fix(cli): standardize --help flag descriptions and "agentic workflow" terminology #20375

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cdb0d77
Initial plan
Copilot Mar 10, 2026
fefc5e2
fix: standardize CLI help flag descriptions and terminology
Copilot Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions cmd/gh-aw/help_flag_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
//go:build !integration

package main

import (
"strings"
"testing"

"github.com/spf13/cobra"
)

// TestHelpFlagConsistency verifies that all commands have consistent --help flag
// descriptions starting with "Show help for gh aw" (matching the root command).
func TestHelpFlagConsistency(t *testing.T) {
var checkCmd func(cmd *cobra.Command)
checkCmd = func(cmd *cobra.Command) {
t.Run("command "+cmd.CommandPath()+" has consistent help flag", func(t *testing.T) {
cmd.InitDefaultHelpFlag()
f := cmd.Flags().Lookup("help")
if f == nil {
t.Skip("Command has no help flag")
}
want := "Show help for gh aw"
if !strings.HasPrefix(f.Usage, want) {
t.Errorf("Command %q help flag Usage = %q, want prefix %q", cmd.CommandPath(), f.Usage, want)
}
Comment on lines +23 to +26
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This test hardcodes the expected help-flag prefix ("Show help for gh aw"). To avoid the test drifting from the CLI’s configured name, derive the expected string from constants.CLIExtensionPrefix (or reuse the same helper used to set the help flag usage).

Copilot uses AI. Check for mistakes.
})
for _, sub := range cmd.Commands() {
checkCmd(sub)
}
}
checkCmd(rootCmd)
}
32 changes: 28 additions & 4 deletions cmd/gh-aw/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,8 @@ For detailed help on any command, use:

var newCmd = &cobra.Command{
Use: "new [workflow]",
Short: "Create a new workflow Markdown file with example configuration",
Long: `Create a new workflow Markdown file with commented examples and explanations of all available options.
Short: "Create a new agentic workflow file with example configuration",
Long: `Create a new agentic workflow file with commented examples and explanations of all available options.

When called without a workflow name (or with --interactive flag), launches an interactive wizard
to guide you through creating a workflow with custom settings.
Expand Down Expand Up @@ -162,7 +162,7 @@ Examples:
var removeCmd = &cobra.Command{
Use: "remove [pattern]",
Short: "Remove agentic workflow files matching the given name prefix",
Long: `Remove workflow files matching the given workflow-id pattern.
Long: `Remove agentic workflow files matching the given workflow-id pattern.

The workflow-id is the basename of the Markdown file without the .md extension.
You can provide a workflow-id prefix to remove multiple workflows, or a specific workflow-id.
Expand Down Expand Up @@ -224,7 +224,7 @@ Examples:

var compileCmd = &cobra.Command{
Use: "compile [workflow]...",
Short: "Compile workflow Markdown files (.md) into GitHub Actions workflows (.lock.yml)",
Short: "Compile agentic workflow files (.md) into GitHub Actions workflows (.lock.yml)",
Long: `Compile one or more agentic workflows to YAML workflows.

If no workflows are specified, all Markdown files in .github/workflows will be compiled.
Expand Down Expand Up @@ -790,6 +790,30 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
rootCmd.AddCommand(completionCmd)
rootCmd.AddCommand(hashCmd)
rootCmd.AddCommand(projectCmd)

// Fix help flag descriptions for all subcommands to be consistent with the
// root command ("Show help for gh aw" vs the Cobra default "help for [cmd]").
var fixSubCmdHelpFlags func(cmd *cobra.Command)
fixSubCmdHelpFlags = func(cmd *cobra.Command) {
cmd.InitDefaultHelpFlag()
if f := cmd.Flags().Lookup("help"); f != nil {
cmdPath := cmd.CommandPath()
// CommandPath() uses Name() which returns the first word of Use
// ("gh" from "gh aw"), so subcommand paths look like "gh compile".
// Replace the leading "gh " prefix with "gh aw " to match the root
// command's display name.
if strings.HasPrefix(cmdPath, "gh ") && !strings.HasPrefix(cmdPath, "gh aw") {
cmdPath = "gh aw " + cmdPath[3:]
Comment on lines +803 to +806
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The help-flag path rewrite and usage text introduce additional hardcoded "gh aw" literals. Consider deriving these from constants.CLIExtensionPrefix (and/or extracting a shared helper with the SetUsageFunc path fixup) to avoid having the CLI name/path-rewrite logic duplicated in multiple places.

Suggested change
// Replace the leading "gh " prefix with "gh aw " to match the root
// command's display name.
if strings.HasPrefix(cmdPath, "gh ") && !strings.HasPrefix(cmdPath, "gh aw") {
cmdPath = "gh aw " + cmdPath[3:]
// Replace the leading root binary prefix (e.g. "gh ") with the full
// CLI extension prefix (e.g. "gh aw ") to match the root command's
// display name, derived from constants.CLIExtensionPrefix.
rootName := strings.Fields(rootCmd.Use)[0]
cliName := string(constants.CLIExtensionPrefix)
if strings.HasPrefix(cmdPath, rootName+" ") && !strings.HasPrefix(cmdPath, cliName+" ") {
cmdPath = cliName + " " + cmdPath[len(rootName)+1:]

Copilot uses AI. Check for mistakes.
}
f.Usage = "Show help for " + cmdPath
}
for _, sub := range cmd.Commands() {
fixSubCmdHelpFlags(sub)
}
}
for _, sub := range rootCmd.Commands() {
fixSubCmdHelpFlags(sub)
}
}

func main() {
Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/add_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ func NewAddCommand(validateEngine func(string) error) *cobra.Command {
cmd := &cobra.Command{
Use: "add <workflow>...",
Short: "Add agentic workflows from repositories to .github/workflows",
Long: `Add one or more workflows from repositories to .github/workflows.
Long: `Add one or more agentic workflows from repositories to .github/workflows.

This command adds workflows directly without interactive prompts. Use 'add-wizard'
for a guided setup that configures secrets, creates a pull request, and more.
Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/fix_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ func NewFixCommand() *cobra.Command {
cmd := &cobra.Command{
Use: "fix [workflow]...",
Short: "Apply automatic codemod-style fixes to agentic workflow files",
Long: `Apply automatic codemod-style fixes to agentic workflow Markdown files.
Long: `Apply automatic codemod-style fixes to agentic workflow files.

This command applies a registry of codemods that automatically update deprecated fields
and migrate to new syntax. Codemods preserve formatting and comments as much as possible.
Expand Down
Loading