Skip to content

Resolve CLI help consistency gaps across init, trial, mcp add, and logs #27861

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
Apr 22, 2026
Merged

Resolve CLI help consistency gaps across init, trial, mcp add, and logs #27861

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
41e80a2
Initial plan
Copilot Apr 22, 2026
23f3e0f
fix(cli): align help text and flag descriptions for consistency
Copilot Apr 22, 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
3 changes: 0 additions & 3 deletions pkg/cli/init_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,6 @@ func NewInitCommand() *cobra.Command {
Short: "Initialize the repository for agentic workflows",
Long: `Initialize the repository for agentic workflows by configuring .gitattributes and creating the dispatcher agent file.

Usage:
gh aw init

This command performs non-interactive repository setup and does not prompt for
engine selection or secret configuration.

Expand Down
4 changes: 4 additions & 0 deletions pkg/cli/init_command_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,10 @@ func TestInitCommandHelp(t *testing.T) {
if !strings.Contains(helpText, "non-interactive repository setup") {
t.Error("Expected help text to mention non-interactive setup")
}

if strings.Contains(helpText, "Usage:") {
t.Error("Expected init long help text to not embed a Usage section")
}
}

func TestInitCommandInteractiveModeDetection(t *testing.T) {
Expand Down
4 changes: 3 additions & 1 deletion pkg/cli/logs_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,8 @@ Examples:
` + string(constants.CLIExtensionPrefix) + ` logs --safe-output missing-tool # Filter logs with missing-tool messages
` + string(constants.CLIExtensionPrefix) + ` logs --safe-output missing-data # Filter logs with missing-data messages
` + string(constants.CLIExtensionPrefix) + ` logs --safe-output create-issue # Filter logs with create-issue messages
` + string(constants.CLIExtensionPrefix) + ` logs --safe-output noop # Filter logs with noop messages
` + string(constants.CLIExtensionPrefix) + ` logs --safe-output report-incomplete # Filter logs with report-incomplete messages
` + string(constants.CLIExtensionPrefix) + ` logs --ref main # Filter logs by branch or tag
` + string(constants.CLIExtensionPrefix) + ` logs --ref feature-xyz # Filter logs by feature branch
` + string(constants.CLIExtensionPrefix) + ` logs --filtered-integrity # Filter logs with DIFC (data integrity flow control) integrity-filtered items in the gateway logs
Expand Down Expand Up @@ -202,7 +204,7 @@ Examples:
logsCmd.Flags().Bool("no-staged", false, "Filter out staged workflow runs")
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().String("safe-output", "", "Filter to runs containing a specific safe output type (e.g., create-issue, missing-tool, missing-data)")
logsCmd.Flags().String("safe-output", "", "Filter to runs containing a specific safe output type (e.g., create-issue, missing-tool, missing-data, noop, report-incomplete)")
logsCmd.Flags().Bool("filtered-integrity", false, "Filter to runs with DIFC (data integrity flow control) integrity-filtered items in the gateway logs")
logsCmd.Flags().Bool("parse", false, "Run JavaScript parsers on agent logs and firewall logs, writing Markdown to log.md and firewall.md")
addJSONFlag(logsCmd)
Expand Down
7 changes: 7 additions & 0 deletions pkg/cli/logs_command_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,9 +251,16 @@ func TestLogsCommandHelpText(t *testing.T) {
"Downloaded artifacts include:",
"Examples:",
"gh aw logs",
"--safe-output noop",
"--safe-output report-incomplete",
}

for _, section := range expectedSections {
assert.Contains(t, cmd.Long, section, "Long description should contain: %s", section)
}

safeOutputFlag := cmd.Flags().Lookup("safe-output")
require.NotNil(t, safeOutputFlag, "safe-output flag should exist")
assert.Contains(t, safeOutputFlag.Usage, "noop", "safe-output flag help should mention noop")
assert.Contains(t, safeOutputFlag.Usage, "report-incomplete", "safe-output flag help should mention report-incomplete")
}
2 changes: 1 addition & 1 deletion pkg/cli/mcp_add.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,7 +361,7 @@ Registry URL defaults to: https://api.mcp.github.com/v0.1`,
}

cmd.Flags().StringVar(&registryURL, "registry", "", "MCP registry URL (default: https://api.mcp.github.com/v0.1)")
cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, http, docker)")
cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, HTTP, Docker)")
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

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

The --transport help text lists values "HTTP" and "Docker", but the implementation only accepts lowercase values (see createMCPToolConfig switch on preferredTransport: "stdio", "http", "docker"). As written, users following the help and passing "--transport HTTP" or "--transport Docker" will get an unsupported transport error. Either keep the help values lowercase, or normalize the flag value (e.g., strings.ToLower) and update the error message so the documented values are actually accepted.

Suggested change
cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, HTTP, Docker)")
cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, http, docker)")

Copilot uses AI. Check for mistakes.
cmd.Flags().StringVar(&customToolID, "tool-id", "", "Custom tool ID to use in the workflow (default: uses server ID)")

return cmd
Expand Down
10 changes: 7 additions & 3 deletions pkg/cli/mcp_add_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,15 +157,19 @@ This is a test workflow.
}
}

func TestMCPAddTransportFlagDescriptionUsesLowercaseDocker(t *testing.T) {
func TestMCPAddTransportFlagDescriptionIncludesCapitalizedHTTPAndDocker(t *testing.T) {
cmd := NewMCPAddSubcommand()
transportFlag := cmd.Flags().Lookup("transport")
if transportFlag == nil {
t.Fatal("expected --transport flag to exist")
}

if !strings.Contains(transportFlag.Usage, "docker") {
t.Fatalf("expected --transport usage to include docker, got: %s", transportFlag.Usage)
if !strings.Contains(transportFlag.Usage, "HTTP") {
t.Fatalf("expected --transport usage to include HTTP, got: %s", transportFlag.Usage)
}

if !strings.Contains(transportFlag.Usage, "Docker") {
t.Fatalf("expected --transport usage to include Docker, got: %s", transportFlag.Usage)
}
}
Comment on lines +160 to 174
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

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

This test enforces capitalized "HTTP"/"Docker" in the --transport usage, but the command currently only supports lowercase transport values ("http", "docker"). Unless the implementation is updated to accept case-insensitive values, this will lock in help text that suggests invalid inputs. Consider asserting for the actual accepted tokens or updating the transport parsing to accept the capitalized forms documented in help.

See below for a potential fix:

func TestMCPAddTransportFlagDescriptionIncludesAcceptedTransportTokens(t *testing.T) {
	cmd := NewMCPAddSubcommand()
	transportFlag := cmd.Flags().Lookup("transport")
	if transportFlag == nil {
		t.Fatal("expected --transport flag to exist")
	}

	if !strings.Contains(transportFlag.Usage, "http") {
		t.Fatalf("expected --transport usage to include http, got: %s", transportFlag.Usage)
	}

	if !strings.Contains(transportFlag.Usage, "docker") {
		t.Fatalf("expected --transport usage to include docker, got: %s", transportFlag.Usage)

Copilot uses AI. Check for mistakes.

Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/trial_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ Trial results are saved both locally (in trials/ directory) and in the host repo

// Add flags
cmd.Flags().StringP("logical-repo", "l", "", "Repository to simulate workflow execution against, as if the workflow was installed there (defaults to current repository)")
cmd.Flags().String("clone-repo", "", "Alternative to --logical-repo: clone the contents of the specified repo into the host repo instead of using logical repository simulation")
cmd.Flags().String("clone-repo", "", "Clone the contents of the specified repository into the host repository before execution (useful for testing against actual repository state)")

cmd.Flags().String("host-repo", "", "Custom host repository slug (defaults to '<username>/gh-aw-trial'). Use '.' for current repository")
cmd.Flags().String("repo", "", "Alias for --host-repo: the repository where workflows are installed and run (note: different semantics from --repo in other commands)")
Expand Down
16 changes: 16 additions & 0 deletions pkg/cli/trial_command_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,22 @@ import (
"github.com/github/gh-aw/pkg/testutil"
)

func TestNewTrialCommandCloneRepoFlagDescription(t *testing.T) {
cmd := NewTrialCommand(func(string) error { return nil })
cloneRepoFlag := cmd.Flags().Lookup("clone-repo")
if cloneRepoFlag == nil {
t.Fatal("Expected 'clone-repo' flag to be defined")
}

if strings.Contains(cloneRepoFlag.Usage, "Alternative to --logical-repo") {
t.Errorf("Expected clone-repo help text to avoid describing itself as an alternative to logical-repo, got: %s", cloneRepoFlag.Usage)
}

if !strings.Contains(cloneRepoFlag.Usage, "Clone the contents of the specified repository") {
t.Errorf("Expected clone-repo help text to describe clone behavior, got: %s", cloneRepoFlag.Usage)
}
}

// Test the host repo slug processing logic with dot notation
func TestHostRepoSlugProcessing(t *testing.T) {
testCases := []struct {
Expand Down
Loading