From 2e9f9167f227f9eb571d008082cd050a305e1ac7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 16:36:03 +0000 Subject: [PATCH 1/2] Initial plan From 6b935c2b943bf296c0700d989cba02dcb174b929 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 17:05:15 +0000 Subject: [PATCH 2/2] fix: CLI consistency improvements - help text, docs, and flag descriptions - Redundant JSON flags: remove 'json' from --format in audit diff and audit report - DIFC acronym: expand to 'data integrity flow control' in logs --filtered-integrity - Timeout units: clarify minutes vs seconds in trial and logs help text - upgrade --no-fix: reword description to clarify it skips codemods, updates, and compilation - init --no-mcp: fix 'GH-AW' to 'gh-aw' lowercase - add --repo: hide unused flag that was defined but never read - audit short description: shorten for clarity - docs/cli.md: fix init description, replace unsupported wildcard example in add, add more examples to remove section, update format options for audit diff/report" Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f8063780-e7df-480c-b8e8-f494f0c1e3d3 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/cli.md | 18 +++++++++++------- pkg/cli/add_command.go | 6 +++++- pkg/cli/audit.go | 2 +- pkg/cli/audit_diff_command.go | 2 +- pkg/cli/audit_report_cross_run_command.go | 2 +- pkg/cli/init_command.go | 2 +- pkg/cli/logs_command.go | 6 +++--- pkg/cli/trial_command.go | 2 +- pkg/cli/upgrade_command.go | 2 +- 9 files changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index b4dffb8e669..dd4e5a2aa2f 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -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 @@ -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` @@ -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` @@ -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` @@ -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 ``` +**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. diff --git a/pkg/cli/add_command.go b/pkg/cli/add_command.go index f193d667c59..00c7ec40c18 100644 --- a/pkg/cli/add_command.go +++ b/pkg/cli/add_command.go @@ -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") diff --git a/pkg/cli/audit.go b/pkg/cli/audit.go index 7289a0611eb..1da31970af6 100644 --- a/pkg/cli/audit.go +++ b/pkg/cli/audit.go @@ -28,7 +28,7 @@ var auditLog = logger.New("cli:audit") func NewAuditCommand() *cobra.Command { cmd := &cobra.Command{ Use: "audit ", - 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. diff --git a/pkg/cli/audit_diff_command.go b/pkg/cli/audit_diff_command.go index 6ae480942f5..1e8f10031fd 100644 --- a/pkg/cli/audit_diff_command.go +++ b/pkg/cli/audit_diff_command.go @@ -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 } diff --git a/pkg/cli/audit_report_cross_run_command.go b/pkg/cli/audit_report_cross_run_command.go index f53be34511e..a9de36a49c1 100644 --- a/pkg/cli/audit_report_cross_run_command.go +++ b/pkg/cli/audit_report_cross_run_command.go @@ -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 } diff --git a/pkg/cli/init_command.go b/pkg/cli/init_command.go index d1eab2ec7f2..bc10034cdba 100644 --- a/pkg/cli/init_command.go +++ b/pkg/cli/init_command.go @@ -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 = " " diff --git a/pkg/cli/logs_command.go b/pkg/cli/logs_command.go index 2ea9ccf010e..cc583998b3e 100644 --- a/pkg/cli/logs_command.go +++ b/pkg/cli/logs_command.go @@ -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 @@ -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") diff --git a/pkg/cli/trial_command.go b/pkg/cli/trial_command.go index 89d07db4e11..c8d9cc94f11 100644 --- a/pkg/cli/trial_command.go +++ b/pkg/cli/trial_command.go @@ -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") 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") diff --git a/pkg/cli/upgrade_command.go b/pkg/cli/upgrade_command.go index 186b0ad13b9..db6530d876a 100644 --- a/pkg/cli/upgrade_command.go +++ b/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, "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")