Skip to content

fix: address CLI consistency issues - redundant flags, unexplained jargon, and doc discrepancies #23750

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 31, 2026
Merged

fix: address CLI consistency issues - redundant flags, unexplained jargon, and doc discrepancies #23750

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
2e9f916
Initial plan
Copilot Mar 31, 2026
6b935c2
fix: CLI consistency improvements - help text, docs, and flag descrip…
Copilot Mar 31, 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
18 changes: 11 additions & 7 deletions docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ Commands are organized by workflow lifecycle: creating, building, testing, monit

#### `init`

Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher agent file (`.github/agents/agentic-workflows.agent.md`), and logs `.gitignore`. Enables MCP server integration by default (use `--no-mcp` to skip). Without arguments, enters interactive mode for engine selection and secret configuration.
Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher agent file (`.github/agents/agentic-workflows.agent.md`). Enables MCP server integration by default (use `--no-mcp` to skip). Without arguments, enters interactive mode for engine selection and secret configuration.

```bash wrap
gh aw init # Interactive mode: select engine and configure secrets
Expand Down Expand Up @@ -159,12 +159,12 @@ Add workflows from The Agentics collection or other repositories to `.github/wor

```bash wrap
gh aw add githubnext/agentics/ci-doctor # Add single workflow
gh aw add "githubnext/agentics/ci-*" # Add multiple with wildcards
gh aw add githubnext/agentics/ci-doctor@v1.0.0 # Add specific version
gh aw add ci-doctor --dir shared # Organize in subdirectory
gh aw add ci-doctor --create-pull-request # Create PR instead of commit
```

**Options:** `--dir/-d`, `--repo/-r`, `--create-pull-request`, `--no-gitattributes`, `--append`, `--disable-security-scanner`, `--engine/-e`, `--force/-f`, `--name/-n`, `--no-stop-after`, `--stop-after`
**Options:** `--dir/-d`, `--create-pull-request`, `--no-gitattributes`, `--append`, `--disable-security-scanner`, `--engine/-e`, `--force/-f`, `--name/-n`, `--no-stop-after`, `--stop-after`

#### `new`

Expand Down Expand Up @@ -434,7 +434,7 @@ gh aw audit diff 12345 12346 --repo owner/repo # Specify repository

The diff output shows: new or removed network domains, status changes (allowed ↔ denied), volume changes (>100% threshold), MCP tool invocation changes, and run metric comparisons (token usage, duration, turns).

**Options:** `--format` (pretty, markdown, json; default: pretty), `--json`, `--repo/-r`
**Options:** `--format` (pretty, markdown; default: pretty), `--json`, `--repo/-r`

##### `audit report`

Expand All @@ -450,7 +450,7 @@ gh aw audit report --repo owner/repo --last 10 # Report on a specif

Output is Markdown by default (suitable for security reviews, piping to files, or `$GITHUB_STEP_SUMMARY`).

**Options:** `--workflow/-w` (filter by workflow name or filename), `--last` (number of recent runs to analyze; default: 20, max: 50), `--format` (markdown, pretty, json; default: markdown), `--json`, `--repo/-r`
**Options:** `--workflow/-w` (filter by workflow name or filename), `--last` (number of recent runs to analyze; default: 20, max: 50), `--format` (markdown, pretty; default: markdown), `--json`, `--repo/-r`

#### `health`

Expand Down Expand Up @@ -513,12 +513,16 @@ gh aw disable ci-doctor --repo owner/repo # Disable in specific repository

#### `remove`

Remove workflows (both `.md` and `.lock.yml`).
Remove workflows (both `.md` and `.lock.yml`). Accepts a workflow ID (basename without `.md`) or prefix pattern. By default, also removes orphaned include files no longer referenced by any workflow.

```bash wrap
gh aw remove my-workflow
gh aw remove my-workflow # Remove specific workflow
gh aw remove test- # Remove all workflows starting with 'test-'
gh aw remove my-workflow --keep-orphans # Remove but keep orphaned include files
Comment on lines +516 to +521
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

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

The remove command’s matching logic uses a case-insensitive substring match on workflow ID/name (strings.Contains), not a prefix-only pattern. The docs currently state “prefix pattern” and the example implies starts-with behavior; please adjust the wording/example to reflect substring matching (or update the implementation to enforce prefix matching).

See below for a potential fix:

Remove workflows (both `.md` and `.lock.yml`). Accepts a workflow ID (basename without `.md`) or case-insensitive substring pattern. By default, also removes orphaned include files no longer referenced by any workflow.

```bash wrap
gh aw remove my-workflow                 # Remove specific workflow
gh aw remove test-                       # Remove all workflows with 'test-' in the ID or name

Copilot uses AI. Check for mistakes.
```

**Options:** `--keep-orphans`

#### `update`

Update workflows based on `source` field (`owner/repo/path@ref`). By default, performs a 3-way merge to preserve local changes; use `--no-merge` to override with upstream. Semantic versions update within same major version.
Expand Down
6 changes: 5 additions & 1 deletion pkg/cli/add_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,8 +129,12 @@ Note: For guided interactive setup, use the 'add-wizard' command instead.`,
// Add AI flag to add command
addEngineFlag(cmd)

// Add repository flag to add command
// Add repository flag to add command.
// Note: the repo is specified directly in the workflow path argument (e.g., "owner/repo/workflow-name"),
// so this flag is not read by the command. It is kept hidden to avoid breaking existing scripts
// that may pass --repo but should not be advertised in help text.
cmd.Flags().StringP("repo", "r", "", "Source repository containing workflows (owner/repo format)")
_ = cmd.Flags().MarkHidden("repo") // Hidden: repo is already embedded in the workflow path spec

// Add PR flag to add command (--create-pull-request with --pr as alias)
cmd.Flags().Bool("create-pull-request", false, "Create a pull request with the workflow changes")
Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/audit.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ var auditLog = logger.New("cli:audit")
func NewAuditCommand() *cobra.Command {
cmd := &cobra.Command{
Use: "audit <run-id-or-url>",
Short: "Audit a workflow run given a run ID or URL and generate a detailed report",
Short: "Audit a workflow run and generate a detailed report",
Long: `Audit a single workflow run by downloading artifacts and logs, detecting errors,
analyzing MCP tool usage, and generating a concise Markdown report suitable for AI agents.

Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/audit_diff_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Examples:
addOutputFlag(cmd, defaultLogsOutputDir)
addJSONFlag(cmd)
addRepoFlag(cmd)
cmd.Flags().String("format", "pretty", "Output format: pretty, markdown, json")
cmd.Flags().String("format", "pretty", "Output format: pretty, markdown")

return cmd
}
Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/audit_report_cross_run_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Examples:
addRepoFlag(cmd)
cmd.Flags().StringP("workflow", "w", "", "Filter by workflow name or filename")
cmd.Flags().Int("last", 20, "Number of recent runs to analyze (max 50)")
cmd.Flags().String("format", "markdown", "Output format: markdown, pretty, json")
cmd.Flags().String("format", "markdown", "Output format: markdown, pretty")

return cmd
}
Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/init_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ Examples:

cmd.Flags().StringP("engine", "e", "", "Override AI engine (claude, codex, copilot, custom)")
_ = cmd.Flags().MarkHidden("engine") // Hide the engine flag from help output (internal use only)
cmd.Flags().Bool("no-mcp", false, "Skip configuring GH-AW MCP server integration for GitHub Copilot Agent")
cmd.Flags().Bool("no-mcp", false, "Skip configuring gh-aw MCP server integration for GitHub Copilot Agent")
cmd.Flags().String("codespaces", "", "Create devcontainer.json for GitHub Codespaces with agentic workflows support. Specify comma-separated repository names in the same organization (e.g., repo1,repo2), or use without value for current repo only")
// NoOptDefVal allows using --codespaces without a value (returns empty string when no value provided)
cmd.Flags().Lookup("codespaces").NoOptDefVal = " "
Expand Down
6 changes: 3 additions & 3 deletions pkg/cli/logs_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Examples:
` + string(constants.CLIExtensionPrefix) + ` logs --safe-output create-issue # Filter logs with create-issue 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 integrity-filtered items in gateway logs
` + string(constants.CLIExtensionPrefix) + ` logs --filtered-integrity # Filter logs with DIFC (data integrity flow control) integrity-filtered items in gateway logs

# Run ID range filtering
` + string(constants.CLIExtensionPrefix) + ` logs --after-run-id 1000 # Filter runs after run ID 1000
Expand Down Expand Up @@ -193,10 +193,10 @@ Examples:
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().Bool("filtered-integrity", false, "Filter to runs with DIFC integrity-filtered items in the gateway logs")
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)
logsCmd.Flags().Int("timeout", 0, "Download timeout in seconds (0 = no timeout)")
logsCmd.Flags().Int("timeout", 0, "Download timeout in seconds (0 = no timeout; note: trial uses minutes for its timeout)")
logsCmd.Flags().String("summary-file", "summary.json", "Path to write the summary JSON file relative to output directory (use empty string to disable)")
logsCmd.MarkFlagsMutuallyExclusive("firewall", "no-firewall")

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 @@ -187,7 +187,7 @@ Trial results are saved both locally (in trials/ directory) and in the host repo
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, "Show what would be done without making any changes")
cmd.Flags().Int("timeout", 30, "Execution timeout in minutes")
cmd.Flags().Int("timeout", 30, "Execution timeout in minutes (e.g., 30 for 30 minutes)")
cmd.Flags().String("trigger-context", "", "Trigger context URL (e.g., GitHub issue URL) for issue-triggered workflows")
Comment on lines 188 to 191
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

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

PR description says the timeout flags (trial in minutes vs logs in seconds) now cross-reference each other, but trial's --timeout help text doesn’t mention logs’ seconds-based timeout (only gives an example). Consider adding a brief note mirroring logs’ help (e.g., that logs uses seconds) or update the PR description to match the actual change.

Copilot uses AI. Check for mistakes.
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")
Expand Down
2 changes: 1 addition & 1 deletion pkg/cli/upgrade_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ Examples:
}

cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: .github/workflows)")
cmd.Flags().Bool("no-fix", false, "Skip codemods, action updates, and workflow compilation (only update agent files)")
cmd.Flags().Bool("no-fix", false, "Only update agent files (skips codemods, action version updates, and workflow compilation)")
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")
Expand Down
Loading