Summary
Automated CLI consistency inspection found 8 issues across the gh-aw CLI help text and documentation.
| Severity |
Count |
| High |
1 |
| Medium |
4 |
| Low |
3 |
High Severity
H1 — Broken/Malformed URL in gh aw project new --help
Affected command: gh aw project new
Exact CLI output:
See https://github.github.com/gh-aw/reference/auth-projects/.
Expected:
See https://github.github.com/gh-aw/reference/auth-projects/.
The URL https://github.github.com/... is malformed — github.github.com is not a valid host. The correct host should be github.com (i.e., https://github.com/github/gh-aw/...) or the internal docs hostname (e.g., `(githubnext.github.io/redacted)
Suggested fix: Correct the URL to point to the actual authentication documentation page.
Priority: High — users following this link will get a connection error.
Medium Severity (4 issues)
M1 — audit --artifacts default differs from logs default (inconsistency between siblings)
Affected commands: gh aw audit, gh aw logs
CLI output — audit:
--artifacts strings Artifact sets to download (default: all). Valid sets: activation, agent, all, detection, experiment, firewall, github-api, mcp, usage
CLI output — logs:
--artifacts strings Artifact sets to download (default: usage). Use 'all' for everything... (default [usage])
Issue: audit defaults to all while logs defaults to usage. This is likely intentional (audit needs full context), but it is undocumented and creates user confusion since the two commands look symmetric. Neither command explains why the defaults differ.
Suggested fix: Add a brief note in each command's description explaining the default artifact set choice (e.g., "Defaults to all because auditing requires comprehensive artifacts for analysis." in audit; "Defaults to usage (compact summary) for faster downloads; use --artifacts all for full logs." in logs).
Priority: Medium — affects usability and discoverability.
M2 — upgrade --pre-releases example comment inconsistent with flag description
Affected command: gh aw upgrade
Example comment in help:
gh aw upgrade --pre-releases # Include prerelease versions when self-upgrading the extension (stable releases are the default)
Flag description:
--pre-releases Include pre-release versions when checking for extension upgrades; pre-releases are installed by exact tag
Issue: The example says "self-upgrading the extension" (implying the CLI binary itself is upgraded), while the flag description says "checking for extension upgrades" (suggesting a check phase only). These describe subtly different behaviors. Additionally, the example comment uses "prerelease" (one word) while the flag description uses "pre-release" (hyphenated). The flag name itself is --pre-releases (hyphenated plural).
Suggested fix: Align the example comment to match the flag description wording. Pick one spelling ("pre-release" or "prerelease") and use it consistently.
Priority: Medium — misleading wording about whether the command actually upgrades or only checks.
M3 — add-wizard missing --append and --no-security-scanner flags present in add
Affected commands: gh aw add, gh aw add-wizard
Flags present in add but absent from add-wizard:
--append string — Append extra content to the end of agentic workflow on installation--no-security-scanner — Disable security scanning of workflow markdown content
Issue: add-wizard wraps add functionality with an interactive layer, but it omits two flags that are exposed by add. Users who need to append content or disable the security scanner when using the wizard have no way to do so without falling back to the non-interactive add command.
The docs/src/content/docs/setup/cli.md documentation for add-wizard does not list these options either (line 169 lists: --no-secret, --dir/-d, --engine/-e, --no-gitattributes, --no-stop-after, --stop-after).
Suggested fix: Either add --append and --no-security-scanner to add-wizard, or document in the add-wizard help that these flags are not available in wizard mode and users should use add instead.
Priority: Medium — feature gap between sibling commands, creates confusion.
M4 — env get defaults to file.yml but help says "When [file] is omitted, the command writes to file.yml"
Affected commands: gh aw env get, gh aw env update
CLI output — env get:
When [file] is omitted, the command writes to file.yml.
CLI output — env update:
When [file] is omitted, the command reads from file.yml.
Issue: The literal filename file.yml is not a meaningful default filename for the user — it reads as a placeholder (like <file>.yml) rather than an actual filename. If file.yml is genuinely the hardcoded default filename, the help text should clarify this explicitly (e.g., "defaults to file.yml in the current directory"). If it was intended to show a placeholder, it should use angle brackets or a more descriptive name (e.g., defaults.yml or <filename>.yml).
Suggested fix: Clarify whether file.yml is the actual default filename or a placeholder. If it is literal, add a note that it writes/reads ./file.yml. If it is a placeholder, rewrite to e.g. When [file] is omitted, defaults to <file>.yml in the current directory.
Priority: Medium — confusing help text for new users.
Low Severity (3 issues)
L1 — init --codespaces "" example has inconsistent trailing whitespace alignment
Affected command: gh aw init
CLI output (examples section):
gh aw init --codespaces "" # Configure Codespaces for current repo only
gh aw init --codespaces repo1,repo2 # Codespaces with additional repos
Issue: The first example has 15 spaces before # and the second has 7 spaces, but the two --codespaces argument values have different lengths ("" vs repo1,repo2), making this inconsistency in alignment look unintentional. All other example-comment columns in the same block use consistent alignment.
Suggested fix: Align comment columns in the examples block consistently, or use a single space before # throughout.
Priority: Low — cosmetic.
L2 — logs help body text says "default only the compact usage artifact" (grammatical)
Affected command: gh aw logs
CLI output:
By default only the compact usage artifact is downloaded (token usage, run metadata).
Issue: The preceding paragraph says: "By default only the compact usage artifact is downloaded" — this is grammatically correct but is inconsistent with the flag description wording which says "Artifact sets to download (default: usage). Use 'all' for everything". The word "compact" appears only in the body prose and not in the flag description, creating inconsistency about what "usage" means.
Suggested fix: Either add "compact" to the flag description (e.g., (default: usage — compact summary)) or remove "compact" from the prose and rely solely on the term "usage" consistently throughout.
Priority: Low — minor terminology inconsistency.
L3 — project new example block trailing whitespace
Affected command: gh aw project new
CLI output (examples section):
gh aw project new "Team Board" --owner myorg # Create org project
Issue: The line # Create org project has two trailing spaces after the comment. This is likely unintentional.
Suggested fix: Remove trailing whitespace from the example comment.
Priority: Low — cosmetic.
Inspection Metadata
| Field |
Value |
| Date |
2026-07-06 |
| Method |
Live ./gh-aw [command] --help output + docs/src/content/docs/setup/cli.md comparison |
| Commands inspected |
38 (all top-level and subcommands) |
| Total issues found |
8 |
| Workflow run |
28798194943 |
Commands Inspected
add, add-wizard, audit, checks, compile, completion, completion install, deploy, disable, domains, enable, env, env get, env update, fix, forecast, hash-frontmatter, health, init, lint, list, logs, mcp, mcp add, mcp inspect, mcp list, mcp list-tools, mcp-server, new, outcomes, outcomes history, pr, pr transfer, project, project new, remove, run, secrets, secrets bootstrap, secrets set, status, trial, update, upgrade, validate, version
Generated by ✅ CLI Consistency Checker · 177.2 AIC · ⌖ 11.1 AIC · ⊞ 4.5K · ◷
Summary
Automated CLI consistency inspection found 8 issues across the
gh-awCLI help text and documentation.High Severity
H1 — Broken/Malformed URL in
gh aw project new --helpAffected command:
gh aw project newExact CLI output:
Expected:
The URL
https://github.github.com/...is malformed —github.github.comis not a valid host. The correct host should begithub.com(i.e.,https://github.com/github/gh-aw/...) or the internal docs hostname (e.g., `(githubnext.github.io/redacted)Suggested fix: Correct the URL to point to the actual authentication documentation page.
Priority: High — users following this link will get a connection error.
Medium Severity (4 issues)
M1 —
audit--artifactsdefault differs fromlogsdefault (inconsistency between siblings)Affected commands:
gh aw audit,gh aw logsCLI output — audit:
CLI output — logs:
Issue:
auditdefaults toallwhilelogsdefaults tousage. This is likely intentional (audit needs full context), but it is undocumented and creates user confusion since the two commands look symmetric. Neither command explains why the defaults differ.Suggested fix: Add a brief note in each command's description explaining the default artifact set choice (e.g., "Defaults to
allbecause auditing requires comprehensive artifacts for analysis." inaudit; "Defaults tousage(compact summary) for faster downloads; use--artifacts allfor full logs." inlogs).Priority: Medium — affects usability and discoverability.
M2 —
upgrade --pre-releasesexample comment inconsistent with flag descriptionAffected command:
gh aw upgradeExample comment in help:
Flag description:
Issue: The example says "self-upgrading the extension" (implying the CLI binary itself is upgraded), while the flag description says "checking for extension upgrades" (suggesting a check phase only). These describe subtly different behaviors. Additionally, the example comment uses "prerelease" (one word) while the flag description uses "pre-release" (hyphenated). The flag name itself is
--pre-releases(hyphenated plural).Suggested fix: Align the example comment to match the flag description wording. Pick one spelling ("pre-release" or "prerelease") and use it consistently.
Priority: Medium — misleading wording about whether the command actually upgrades or only checks.
M3 —
add-wizardmissing--appendand--no-security-scannerflags present inaddAffected commands:
gh aw add,gh aw add-wizardFlags present in
addbut absent fromadd-wizard:--append string— Append extra content to the end of agentic workflow on installation--no-security-scanner— Disable security scanning of workflow markdown contentIssue:
add-wizardwrapsaddfunctionality with an interactive layer, but it omits two flags that are exposed byadd. Users who need to append content or disable the security scanner when using the wizard have no way to do so without falling back to the non-interactiveaddcommand.The
docs/src/content/docs/setup/cli.mddocumentation foradd-wizarddoes not list these options either (line 169 lists:--no-secret,--dir/-d,--engine/-e,--no-gitattributes,--no-stop-after,--stop-after).Suggested fix: Either add
--appendand--no-security-scannertoadd-wizard, or document in theadd-wizardhelp that these flags are not available in wizard mode and users should useaddinstead.Priority: Medium — feature gap between sibling commands, creates confusion.
M4 —
env getdefaults tofile.ymlbut help says "When [file] is omitted, the command writes to file.yml"Affected commands:
gh aw env get,gh aw env updateCLI output —
env get:CLI output —
env update:Issue: The literal filename
file.ymlis not a meaningful default filename for the user — it reads as a placeholder (like<file>.yml) rather than an actual filename. Iffile.ymlis genuinely the hardcoded default filename, the help text should clarify this explicitly (e.g., "defaults tofile.ymlin the current directory"). If it was intended to show a placeholder, it should use angle brackets or a more descriptive name (e.g.,defaults.ymlor<filename>.yml).Suggested fix: Clarify whether
file.ymlis the actual default filename or a placeholder. If it is literal, add a note that it writes/reads./file.yml. If it is a placeholder, rewrite to e.g.When [file] is omitted, defaults to <file>.yml in the current directory.Priority: Medium — confusing help text for new users.
Low Severity (3 issues)
L1 —
init --codespaces ""example has inconsistent trailing whitespace alignmentAffected command:
gh aw initCLI output (examples section):
Issue: The first example has 15 spaces before
#and the second has 7 spaces, but the two--codespacesargument values have different lengths (""vsrepo1,repo2), making this inconsistency in alignment look unintentional. All other example-comment columns in the same block use consistent alignment.Suggested fix: Align comment columns in the examples block consistently, or use a single space before
#throughout.Priority: Low — cosmetic.
L2 —
logshelp body text says "default only the compact usage artifact" (grammatical)Affected command:
gh aw logsCLI output:
Issue: The preceding paragraph says: "By default only the compact usage artifact is downloaded" — this is grammatically correct but is inconsistent with the flag description wording which says "Artifact sets to download (default: usage). Use 'all' for everything". The word "compact" appears only in the body prose and not in the flag description, creating inconsistency about what "usage" means.
Suggested fix: Either add "compact" to the flag description (e.g.,
(default: usage — compact summary)) or remove "compact" from the prose and rely solely on the term "usage" consistently throughout.Priority: Low — minor terminology inconsistency.
L3 —
project newexample block trailing whitespaceAffected command:
gh aw project newCLI output (examples section):
Issue: The line
# Create org projecthas two trailing spaces after the comment. This is likely unintentional.Suggested fix: Remove trailing whitespace from the example comment.
Priority: Low — cosmetic.
Inspection Metadata
./gh-aw [command] --helpoutput +docs/src/content/docs/setup/cli.mdcomparisonCommands Inspected
add,add-wizard,audit,checks,compile,completion,completion install,deploy,disable,domains,enable,env,env get,env update,fix,forecast,hash-frontmatter,health,init,lint,list,logs,mcp,mcp add,mcp inspect,mcp list,mcp list-tools,mcp-server,new,outcomes,outcomes history,pr,pr transfer,project,project new,remove,run,secrets,secrets bootstrap,secrets set,status,trial,update,upgrade,validate,version