diff --git a/docs/src/content/docs/reference/audit.md b/docs/src/content/docs/reference/audit.md index 17651090811..ed1274c7a75 100644 --- a/docs/src/content/docs/reference/audit.md +++ b/docs/src/content/docs/reference/audit.md @@ -41,6 +41,7 @@ Self-comparisons and duplicate run IDs are rejected when using diff mode. | `--json` | off | Output report as JSON to stdout | | `--parse` | off | Run JavaScript parsers on agent and firewall logs, writing `log.md` and `firewall.md` (single-run only) | | `--repo ` | auto | Specify repository when the run ID is not from a URL | +| `--stdin` | off | Read run IDs or URLs from stdin (one per line) instead of positional arguments | | `--verbose` | off | Print detailed progress information | | `--format ` | `pretty` | Diff output format: `pretty` or `markdown` (multi-run only) | @@ -55,6 +56,17 @@ gh aw audit 1234567890 -o ./audit-reports gh aw audit 1234567890 --repo owner/repo ``` +**Stdin mode:** + +Use `--stdin` to pass run IDs or URLs from a file or pipeline. This is mutually exclusive with positional arguments. Blank lines and lines starting with `#` are ignored. When passing bare numeric IDs (without embedded repo context), `--repo owner/repo` is required. + +```bash +echo "1234567890" | gh aw audit --stdin +echo -e "1234567890\n9876543210" | gh aw audit --stdin # diff mode: first is base +cat run-ids.txt | gh aw audit --stdin +cat run-ids.txt | gh aw audit --stdin --repo owner/repo # required for bare numeric IDs +``` + **Multi-run diff examples:** ```bash @@ -104,12 +116,21 @@ This feature is built into the `gh aw logs` command via the `--format` flag. | `--json` | off | Output cross-run report as JSON (when combined with `--format`) | | `--repo ` | auto | Specify repository | | `-o, --output ` | `./logs` | Directory for downloaded artifacts | +| `--stdin` | off | Read run IDs or URLs from stdin (one per line) instead of run-discovery; content filters still apply | | `--verbose` | off | Print detailed progress | The report output includes an executive summary, domain inventory, metrics trends, MCP server health, and per-run breakdown. It detects cross-run anomalies such as domain access spikes, elevated MCP error rates, and connection rate changes. For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, `effective_tokens`). +**`--stdin` mode:** Pass `--stdin` to supply an explicit list of run IDs or URLs instead of letting the command discover runs from the GitHub API. Date, count, and workflow-name filters are ignored; `--engine`, `--firewall`, `--safe-output`, and other content filters still apply. Blank lines and `#`-prefixed lines are ignored. Bare numeric IDs require `--repo owner/repo`. + +```bash +cat run-ids.txt | gh aw logs --stdin +echo "1234567890" | gh aw logs --stdin --engine claude +cat run-ids.txt | gh aw logs --stdin --repo owner/repo # required for bare numeric IDs +``` + **Examples:** ```bash diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 092c27ddd18..e9526c7ce91 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -411,7 +411,15 @@ gh aw logs --train # Train on last 10 runs gh aw logs my-workflow --train -c 50 # Train on up to 50 runs of a specific workflow ``` -**Options:** `--after`, `--after-run-id`, `--artifacts`, `--before-run-id`, `--count/-c`, `--end-date`, `--engine/-e`, `--filtered-integrity`, `--firewall`, `--format`, `--json/-j`, `--last`, `--no-firewall`, `--no-staged`, `--output/-o`, `--parse`, `--ref`, `--repo/-r`, `--safe-output`, `--start-date`, `--summary-file`, `--timeout`, `--tool-graph`, `--train` +**`--stdin` flag:** Reads run IDs or URLs from stdin (one per line) instead of discovering runs from the GitHub API. Mutually exclusive with the workflow-name positional argument. Date, count, and workflow-name filters are ignored when `--stdin` is set; content filters (`--engine`, `--firewall`, `--safe-output`, etc.) still apply. Blank lines and `#`-prefixed comment lines are ignored. Bare numeric IDs require `--repo owner/repo` because they carry no embedded repo context. Full run URLs are self-contained and do not require `--repo`. + +```bash wrap +cat run-ids.txt | gh aw logs --stdin +echo "1234567890" | gh aw logs --stdin --engine claude +cat run-ids.txt | gh aw logs --stdin --repo owner/repo # required for bare numeric IDs +``` + +**Options:** `--after`, `--after-run-id`, `--artifacts`, `--before-run-id`, `--count/-c`, `--end-date`, `--engine/-e`, `--filtered-integrity`, `--firewall`, `--format`, `--json/-j`, `--last`, `--no-firewall`, `--no-staged`, `--output/-o`, `--parse`, `--ref`, `--repo/-r`, `--safe-output`, `--start-date`, `--stdin`, `--summary-file`, `--timeout`, `--tool-graph`, `--train` #### `audit` @@ -430,7 +438,15 @@ gh aw audit 12345678 --parse # Parse logs to markdo gh aw audit 12345678 --repo owner/repo # Specify repository for bare run ID ``` -**Options:** `--parse`, `--json`, `--repo/-r` +**`--stdin` flag:** Reads run IDs or URLs from stdin (one per line), bypassing the need to pass positional arguments. Mutually exclusive with positional run-ID arguments. Blank lines and `#`-prefixed lines are ignored. Bare numeric IDs require `--repo owner/repo`; full URLs carry their own repo context. + +```bash wrap +echo "1234567890" | gh aw audit --stdin +echo -e "1234567890\n9876543210" | gh aw audit --stdin # diff mode: first is base +cat run-ids.txt | gh aw audit --stdin --repo owner/repo +``` + +**Options:** `--parse`, `--json`, `--repo/-r`, `--stdin` The `--repo` flag accepts `owner/repo` format and is required when passing a bare numeric run ID without a full URL, allowing the command to locate the correct repository.