[cli-consistency] Documentation claims 'audit' command accepts workflow URLs but only accepts run IDs/URLs

[github-actions]

Issue Description

Priority: Low
Type: Documentation clarity

Problem

The audit command documentation is slightly misleading about what types of inputs it accepts.

Documentation Claims (cli.md:392-402)

#### `audit`

Analyze specific runs with overview, metrics, tool usage, MCP failures, firewall analysis, noops, and artifacts. Accepts run IDs, workflow run URLs, job URLs, and step-level URLs. Auto-detects Copilot agent runs for specialized parsing.

When provided with a job URL, automatically extracts logs for the specific job. When a step fragment is included, extracts only that step's output. If no step is specified, automatically identifies and extracts the first failing step.

```bash
gh aw audit 12345678                                      # By run ID
gh aw audit https://github.com/owner/repo/actions/runs/123 # By workflow run URL
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456 # By job URL (extracts first failing step)
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456#step:7:1 # By step URL (extracts specific step)
gh aw audit 12345678 --parse                              # Parse logs to markdown
```

Source Code Reality (audit.go)

From pkg/cli/audit.go:17-23:

Use:   "audit (run-id)",
Short: "Investigate an agentic 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.

This command accepts:

The command signature says (run-id) which is technically correct (it's the GitHub Actions run ID extracted from URLs), but the documentation could be clearer.

Clarification Needed

The command accepts:

1. Run ID (numeric): 12345678
2. Workflow run URL: https://github.com/owner/repo/actions/runs/123
3. Job URL: https://github.com/owner/repo/actions/runs/123/job/456
4. Step URL: https://github.com/owner/repo/actions/runs/123/job/456#step:7:1

All of these extract the run ID internally. The documentation is technically accurate but could be clearer.

Suggested Fix

Update the documentation to clarify that all URL formats extract the run ID:

#### `audit`

Analyze specific runs with overview, metrics, tool usage, MCP failures, firewall analysis, noops, and artifacts. Accepts run IDs (numeric) or URLs that contain run IDs (workflow run URLs, job URLs, step-level URLs). Auto-detects Copilot agent runs for specialized parsing.

The run ID is automatically extracted from any URL format provided.

When provided with a job URL, automatically extracts logs for the specific job. When a step fragment is included, extracts only that step's output. If no step is specified, automatically identifies and extracts the first failing step.

```bash
gh aw audit 12345678                                      # By run ID (numeric)
gh aw audit https://github.com/owner/repo/actions/runs/123 # By workflow run URL
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456 # By job URL (extracts first failing step)
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456#step:7:1 # By step URL (extracts specific step)
gh aw audit 12345678 --parse                              # Parse logs to markdown
```

Run ID from URL: `github.com/owner/repo/actions/runs/12345678` → `12345678`

Related Code

• Documentation: docs/src/content/docs/setup/cli.md:392-402
• Implementation: pkg/cli/audit.go:17-23
  Related to [cli-consistency] CLI Consistency Issues - January 30, 2026 #12740

AI generated by CLI Consistency Checker