Align audit/trial help text and update docs for update --cool-down#31597
Merged
Conversation
Agent-Logs-Url: https://github.com/github/gh-aw/sessions/944c6912-69df-4a67-8704-c5696689bf78 Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Agent-Logs-Url: https://github.com/github/gh-aw/sessions/944c6912-69df-4a67-8704-c5696689bf78 Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Fix inconsistencies in CLI command help text
Align audit/trial help text and update docs for May 11, 2026
update --cool-down
Contributor
There was a problem hiding this comment.
Pull request overview
Updates CLI help/documentation to match actual command behavior and normalizes help text formatting, with regression tests to keep these surfaces consistent.
Changes:
- Update
auditshort help text to reflect multi-run/diff usage. - Normalize
triallong help to a single standardExamples:block. - Document
update --cool-downin setup docs and add focused consistency tests.
Show a summary per file
| File | Description |
|---|---|
| pkg/parser/frontmatter_extraction_test.go | Minor formatting alignment in an existing test case. |
| pkg/cli/trial_command.go | Replaces custom multi-section example headings with a single Examples: section in trial long help. |
| pkg/cli/cli_consistency_help_test.go | Adds unit tests to assert help-text normalization and docs coverage for --cool-down. |
| pkg/cli/audit.go | Updates audit short description to reflect multi-run behavior. |
| docs/src/content/docs/setup/cli.md | Adds --cool-down to the documented update options list. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/5 changed files
- Comments generated: 3
| Short: "Audit a workflow run and generate a detailed report", | ||
| Short: "Audit workflow runs and generate detailed reports", | ||
| Long: `Audit one or more workflow runs by downloading artifacts and logs, detecting errors, | ||
| analyzing MCP tool usage, and generating a concise report suitable for AI agents. |
| updateIndex := strings.Index(text, "#### `update`") | ||
| require.NotEqual(t, -1, updateIndex, "CLI setup docs should contain the update section") | ||
|
|
||
| updateSection := text[updateIndex:] |
| ``` | ||
|
|
||
| **Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile`, `--no-redirect` | ||
| **Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile`, `--no-redirect`, `--cool-down` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The CLI consistency check flagged three help-text issues:
auditdescribed a single-run command while supporting multiple runs,trialused a non-standard examples layout, and theupdatedocs omitted--cool-down.Audit help text
Trial help format
Examples:section used across the CLI.Update docs coverage
--cool-downto theupdateoptions list in the CLI setup docs so the documented surface matches the command help.Regression coverage
auditshort/long description consistencytrialexamples heading and removal of custom subsection labels--cool-downin theupdatedocs sectionExample of the normalized
trialhelp style:Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
https://api.github.com/graphql/usr/bin/gh gh repo view --json owner,name --jq .owner.login + "/" + .name x_amd64/vet(http block)/usr/bin/gh gh repo view --json owner,name --jq .owner.login + "/" + .name n-dir/node(http block)/usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw(http block)https://api.github.com/orgs/owner/actions/secrets/usr/bin/gh gh api /orgs/owner/actions/secrets --jq .secrets[].name(http block)/usr/bin/gh gh api /orgs/owner/actions/secrets --jq .secrets[].name ath ../../../.pr**/*.json --jq ndor/bin/bash g_.a(http block)/usr/bin/gh gh api /orgs/owner/actions/secrets --jq .secrets[].name ath ../../../.prettierignore 64/pkg/tool/linuremote.origin.url /usr/bin/infocmp(http block)https://api.github.com/orgs/test-owner/actions/secrets/usr/bin/gh gh api /orgs/test-owner/actions/secrets --jq .secrets[].name h ../../../.prettierignore(http block)/usr/bin/gh gh api /orgs/test-owner/actions/secrets --jq .secrets[].name th .prettierigno--ignore-path ache/go/1.25.8/x.prettierignore developer-action--log-level=error 0541-18276/test-sh -tests 4756119/b428=> developer-action-main/dist/ripgrep/bin/linux-x64-trimpath er ../pkg/workflow/js/**/*.json' --ignore-path ../../../.prettierignore node bject.type] | @tsv 44449569/001 '/tmp/TestParseDapi(http block)/usr/bin/gh gh api /orgs/test-owner/actions/secrets --jq .secrets[].name d -n 10 r /usr/bin/infocmp "prettier" --wrish git k/gh-aw/gh-aw/ac"prettier" --write '../../../**/*.json' '!../../../pkg/workflow/js/**/*.json' --ignore-path ../../../.prettierignore infocmp -1 ll 2>&1 sh bject.type] | @tsv te '**/*.cjs' '*gh gh bin/sh node(http block)https://api.github.com/repos/actions/ai-inference/git/ref/tags/v1/usr/bin/gh gh api /repos/actions/ai-inference/git/ref/tags/v1 --jq [.object.sha, .object.type] | @tsv 0541-18276/test-278528791 -tests x_amd64/compile(http block)/usr/bin/gh gh api /repos/actions/ai-inference/git/ref/tags/v1 --jq [.object.sha, .object.type] | @tsv ithub/workflows/architecture-guardian.md ema_validation_integration_test.go /bin/sh ignore-path ../.gh R7/sGxKWMUMHbUFlapi bject.type] | @t/repos/actions/github-script/git/ref/tags/v9 /bin/sh -c ithub-script/git/ref/tags/v9.0.0 infocmp ache/node/24.14.1/x64/bin/node ath ../../../.prinfocmp x_amd64/vet bject.type] | @txterm-color node(http block)/usr/bin/gh gh api /repos/actions/ai-inference/git/ref/tags/v1 --jq [.object.sha, .object.type] | @tsv CompiledOutput824303312/001 git ache/node/24.14.1/x64/bin/node t gh /usr/bin/git gcc t-16�� /ref/tags/v9 c sv - origin bject.type] | @txterm-color node(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v3/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v3 --jq [.object.sha, .object.type] | @tsv e formatted" /tmp/go-build1575294089/b090/vet.cfg ache/go/1.25.8/x64/bin/node(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v3 --jq [.object.sha, .object.type] | @tsv *.json' '!../../../pkg/workflow/js/**/*.json' ---errorsas log ache/go/1.25.8/x64/pkg/tool/linux_amd64/cgo ./../.prettieriggh test-branch(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v3 --jq [.object.sha, .object.type] | @tsv c684ad965604278c53efc282:pkg/workflow/compiler.g-errorsas son k/gh-aw/gh-aw/actions/setup/js/node_modules/.bin-nilfunc ithub-script/gitinfocmp ^remote\..*\.gh--1 _id":200}] git ls-f�� rite '**/*.cjs' '**/*.ts' '**/*.json' --ignore-p--detach --others k/_temp/uv-python-dir/sh /ref/tags/v9 gh sv git(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v5/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq [.object.sha, .object.type] | @tsv se 5294089/b217/vet.cfg 64/pkg/tool/linux_amd64/vet son(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq [.object.sha, .object.type] | @tsv 690794556/001 **/*.cjs ache/go/1.25.8/x64/pkg/tool/linux_amd64/link **/*.json --ignore-path ../../../.prettixterm-color ache/go/1.25.8/x64/pkg/tool/linu--jq -c 0541-18276/test-168425470 k/gh-aw/gh-aw/pkg/fileutil/tar.go 4756119/b453/importcfg.link rror(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq [.object.sha, .object.type] | @tsv /tmp/go-build2724756119/b450/stats.test never /usr/bin/git -s -w -buildmode=exe git -C /ref/tags/v9 resolved$ sv(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v6/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv 7917/001/stabili--workflow k/gh-aw/gh-aw/cmnonexistent-workflow 64/pkg/tool/linu--limit ignore(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv edOutput2302756306/001(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv verutil.go verutil_test.go 64/pkg/tool/linux_amd64/compile(http block)https://api.github.com/repos/actions/github-script/git/ref/tags/v8/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq [.object.sha, .object.type] | @tsv runs/20260511-230541-18276/test-543141485/.github/workflows(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq [.object.sha, .object.type] | @tsv -instructions-test-2940828321/.github/workflows -trimpath /usr/lib/git-core/git l github.com/ayman-f1 -lang=go1.24 /usr/lib/git-core/git main�� run l _id":200}] --detach -nolocalimports -importcfg node(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq [.object.sha, .object.type] | @tsv "prettier" --write '**/*.cjs' '**/*.ts' '**/*.json' --ignore-path ../../../.prettierignore ker/docker-init /node_modules/.bin/node xterm-color 64/pkg/tool/linudocker-cli-plugin-metadata /usr/bin/gh node /opt�� licyMinIntegrityOnlymin-integrity_with_explicit_repo865736721/001 --write /usr/bin/git l --ignore-path ../../../.pretti/tmp/gh-aw/aw-feature-branch.patch git(http block)https://api.github.com/repos/actions/github-script/git/ref/tags/v9/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9 --jq [.object.sha, .object.type] | @tsv(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9 --jq [.object.sha, .object.type] | @tsv " -o gh-aw ./cmd/gh-aw(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9 --jq [.object.sha, .object.type] | @tsv yphen3918445350/001' yphen3918445350/001' x_amd64/vet(http block)https://api.github.com/repos/actions/github-script/git/ref/tags/v9.0.0/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9.0.0 --jq [.object.sha, .object.type] | @tsv(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9.0.0 --jq [.object.sha, .object.type] | @tsv cp .github/aw/actions-lock.json -errorsas(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9.0.0 --jq [.object.sha, .object.type] | @tsv -c=4 -nolocalimports -importcfg /tmp/go-build2724756119/b395/importcfg -embedcfg /tmp/go-build2724756119/b395/embedcfg -pack(http block)https://api.github.com/repos/actions/setup-go/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/setup-go/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv g/jsonutil/json.go g/jsonutil/json_test.go ache/go/1.25.8/x64/pkg/tool/linux_amd64/compile -errorsas -ifaceassert name, workflowPaxterm-color ache/go/1.25.8/x64/pkg/tool/linu1 -###�� 0541-18276/test-2213118436 c xpires.lock.yml - b/gh-aw/pkg/jsonapi(http block)/usr/bin/gh gh api /repos/actions/setup-go/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv orts1302429707/0remote.origin.url pkg/workflow/schema_validation_integration_test.go .cfg rror config bject.type] | @txterm-color /opt/hostedtoolcache/go/1.25.8/xTest User -o on rkflow/js/**/*.json ache/go/1.25.8/x64/pkg/tool/linux_amd64/vet erignore main -lang=go1.25 ache/go/1.25.8/x64/pkg/tool/linux_amd64/vet(http block)/usr/bin/gh gh api /repos/actions/setup-go/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv(http block)https://api.github.com/repos/actions/setup-node/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv -unreachable=faltest-logs/run-1 /tmp/go-build1575294089/b011/vet.cfg cal/bin/sh nore(http block)/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv te '../../../**/*.json' '!../../../pkg/workflow/-errorsas -buildtags r: $owner, name: $name) { hasDiscussionsEnabled } } -errorsas -ifaceassert -nilfunc ache/go/1.25.8/x64/pkg/tool/linuREDACTED -V=f�� 0541-18276/test-2213118436/.github/workflows -tests Name,createdAt,startedAt,updatedAt,event,headBranch,headSha,displayTitle(http block)/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv "prettier" --write 'scripts/**/*-f(http block)https://api.github.com/repos/actions/setup-node/git/ref/tags/v6/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv 1269046/001(http block)/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv --noprofile(http block)/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv rity5692782/001(http block)https://api.github.com/repos/actions/upload-artifact/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv(http block)/usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv */*.ts' '**/*.json' --ignore-path ../../../.prettierignore -v ode xterm-color -dwarf=false /opt/hostedtoolcremove bash 1/x6�� y_only_defaults_repo2238475618/001 /opt/hostedtoolc--jq 64/pkg/tool/linux_amd64/vet son /tmp/go-build272-1 sv 64/pkg/tool/linux_amd64/vet(http block)/usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv /*.js' --ignore---detach --jq g_.a -bool -buildtags /opt/hostedtoolcuser.email gh api *.json' '!../../../pkg/workflow/js/**/*.json' ---errorsas --jq /usr/bin/git 2" 1>&2 -tests rue,"errors":[],-v git(http block)https://api.github.com/repos/aws-actions/configure-aws-credentials/git/ref/tags/v4/usr/bin/gh gh api /repos/aws-actions/configure-aws-credentials/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv UA04/Tor76hBZqSk2wpLzUA04 scripts/**/*.js ache/node/24.14.1/x64/bin/node .prettierignore --log-level=erro-1 de/node/bin/git 4756119/b436/importcfg t-27�� bility_SameInputSameOutput3982567917/001/stabili--workflow ../../../**/*.json /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linu--limit --ignore-path ../../../.pretti-c x_amd64/cgo /opt/hostedtoolc/tmp/gh-aw/aw-master.patch(http block)/usr/bin/gh gh api /repos/aws-actions/configure-aws-credentials/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv 4756119/b449/_pkg_.a format:pkg-json ache/go/1.25.8/x64/pkg/tool/linux_amd64/compile(http block)/usr/bin/gh gh api /repos/aws-actions/configure-aws-credentials/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv prettier =master(http block)https://api.github.com/repos/azure/login/git/ref/tags/v2/usr/bin/gh gh api /repos/azure/login/git/ref/tags/v2 --jq [.object.sha, .object.type] | @tsv --write resolved$ ache/node/24.14.1/x64/bin/node .prettierignore --log-level=erro/opt/hostedtoolcache/node/24.14.1/x64/bin/npm -main/dist/gh-gpinstall /opt/hostedtoolc--package-lock-only t-21�� sistency_WithImports663406845/001/main.md(http block)/usr/bin/gh gh api /repos/azure/login/git/ref/tags/v2 --jq [.object.sha, .object.type] | @tsv sistency_GoAndJavaScript1776826870/001/test-frontmatter-with-nested-objects.md ache/node/24.14.1/x64/bin/npm 0207518/b391/vet.cfg pkg/actionpins/dnode 64/pkg/tool/linu/opt/hostedtoolcache/node/24.14.1/x64/bin/npm /usr/bin/infocmpinstall sh -c runs/20260511-231018-28235/test-3767300803/.github/workflows infocmp /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/vet plate-expression/usr/lib/git-core/git /opt/hostedtoolcmaintenance /usr/bin/infocmprun /opt/hostedtoolc--auto(http block)/usr/bin/gh gh api /repos/azure/login/git/ref/tags/v2 --jq [.object.sha, .object.type] | @tsv 3 --write ache/node/24.14.1/x64/bin/node **/*.ts **/*.json --ignore-path node t-23�� k/gh-aw/gh-aw/.github/workflows/ai-moderator.md format:pkg-json /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/vet tierignore --json bject.type] | @trun /opt/hostedtoolc--auto(http block)https://api.github.com/repos/docker/login-action/git/ref/tags/v3/usr/bin/gh gh api /repos/docker/login-action/git/ref/tags/v3 --jq [.object.sha, .object.type] | @tsv 646970706 scripts/**/*.js ache/go/1.25.8/x64/pkg/tool/linux_amd64/compile .prettierignore --log-level=erro/opt/hostedtoolcache/node/24.14.1/x64/bin/npm(http block)/usr/bin/gh gh api /repos/docker/login-action/git/ref/tags/v3 --jq [.object.sha, .object.type] | @tsv sistency_GoAndJavaScript1776826870/001/test-frontmatter-with-env-template-expressions.md infocmp ache/node/24.14.1/x64/bin/node h ../../../.pretnode nly /usr/bin/infocmpinstall 0207518/b391/imp--package-lock-only t-39�� k/gh-aw/gh-aw/.github/workflows/ab-testing-advisor.md infocmp(http block)/usr/bin/gh gh api /repos/docker/login-action/git/ref/tags/v3 --jq [.object.sha, .object.type] | @tsv prettier s ache/node/24.14.1/x64/bin/node **/*.ts **/*.json --ignore-path node t-23�� 319/001 format:pkg-json /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/link tierignore ^remote\..*\.gh-add bject.type] | @t. /opt/hostedtoolcache/go/1.25.8/x--jq(http block)https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v0.1.2/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v0.1.2 --jq [.object.sha, .object.type] | @tsv g/gitutil/gitutil.go g/gitutil/gitutil_test.go /usr/bin/cp(http block)/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v0.1.2 --jq [.object.sha, .object.type] | @tsv SameOutput114032-f --write cal/bin/sh !../../../pkg/wogh --ignore-path ode-gyp-bin/node/repos/actions/github-script/git/ref/tags/v9 bash --no�� 2826170737 infocmp /opt/hostedtoolcache/go/1.25.8/x64/bin/go ignore-path ../.gh f769fdfd bject.type] | @t/repos/actions/github-script/git/ref/tags/v9 go(http block)/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v0.1.2 --jq [.object.sha, .object.type] | @tsv --stateless-rpc --helper-status cfg --verbose --no-progress erignore git show�� CommaSeparatedCompiledOutput1123309837/001 git 1/x64/bin/node 2 remote 64/bin/node 1/x64/bin/node(http block)https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v1.0.0/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v1.0.0 --jq [.object.sha, .object.type] | @tsv /001/inlined-a.md blob in/sh nore(http block)Agent-Logs-Url: REDACTED n-dir/sh /ref/tags/v9 test@example.comconfig sv git -c .json' '!../../../pkg/workflow/js/**/.json' --ignore-path ../../../.prettierignore log ache/go/1.25.8/x64/pkg/tool/linux_amd64/link ./../.prettieriginfocmp --format=format:-1 --end-of-optionsxterm-color ache/go/1.25.8/x64/pkg/tool/linutest@example.com` (http block)
Agent-Logs-Url: https://githu../../../.prettierignore iptables /ref/tags/v9 remote.origin.ur-1 sv cp .git�� mpiledOutput687160085/001 4756119/b478/scripts.test 64/pkg/tool/linux_amd64/vet ./../.prettieriggh /tmp/go-build272run` (http block)
Agent-Logs-Url: https:--log-level=error bject.type] | @TSV 1018-28235/test-gh gh es.lock.yml infocmp` (http block)