[cli-consistency] CLI Consistency Issues - 2026-07-29

[github-actions]

Caution

agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation.

Details

The threat detection engine failed to produce results.

Review the workflow run logs for details.

Summary

Automated inspection of the gh-aw CLI (all top-level commands + subcommands of env, mcp, secrets, pr, project) against its own --help output and docs/src/content/docs/setup/cli.md. Overall the CLI is clean and consistent; a handful of documentation gaps, one inverted convention, and several minor naming inconsistencies were found.

Method: Built gh-aw from source, ran --help for every command/subcommand, captured ~2200 lines of output, and analyzed it with three focused passes: typo/grammar, docs-vs-help diff, and flag-naming consistency.

Severity breakdown: High: 1 · Medium: 6 · Low: 10

---

🔴 High severity

1. audit docs describe wrong default output path

• Docs says (docs/src/content/docs/setup/cli.md): "Logs are saved to logs/run-{id}/ with filenames indicating the extraction level."
• Actual CLI (gh-aw audit --help): -o, --output string Output directory for generated files (default ".github/aw/logs")
• Issue: The real default output path is .github/aw/logs/run-{id}/, not logs/run-{id}/. This could send users looking in the wrong directory.
• Suggested fix: Update docs to say .github/aw/logs/run-{id}/.

---

🟠 Medium severity

6 medium-severity findings (click to expand)

2. audit --artifacts valid values list missing evals

• Docs says: "Valid sets include activation, agent, all, detection, experiment, firewall, github-api, mcp, and usage."
• Actual CLI: --artifacts strings ... Valid sets: activation, agent, all, detection, evals, experiment, firewall, github-api, mcp, usage
• Issue: Docs omit the valid evals artifact set.
• Suggested fix: Add evals to the documented list.

3. fix inverts the --dry-run convention used everywhere else

• Affected commands: run, trial, env update use an opt-in --dry-run flag (dry-run is off by default). fix instead defaults to dry-run and requires an opt-in --write flag: --write Write changes to files (without this flag, no changes are made).
• Issue: Same underlying concept ("preview vs apply changes") is expressed with an inverted flag polarity in fix compared to the rest of the CLI, which can confuse users switching between commands.
• Suggested fix: Either add a --dry-run alias to fix for consistency, or explicitly call out the inverted convention in the command's long description (partially done today via "dry-run by default" but not flagged as an exception to CLI-wide convention).

4. -l shorthand maps to two different flags depending on command

• Affected commands: compile/trial use -l, --logical-repo string (repository to simulate workflow execution against); project new uses -l, --link string (repository to link project to).
• Issue: Same shorthand (-l), different semantics — easy to mistype/misremember across commands.
• Suggested fix: Reserve -l for one meaning CLI-wide, or drop the shorthand alias for one of the two flags.

5. --repo help text format inconsistent across commands (GHES host prefix)

• Affected commands: Most commands (e.g. audit, checks, disable, enable) document --repo as Target repository ([HOST/]owner/repo format). Defaults to current repository. But doctor and env get/env update document it as just Target repository (owner/repo format) — no [HOST/] prefix mentioned.
• Issue: Unclear whether GHES host-qualified repo values (HOST/owner/repo) are supported in doctor/env get/env update, or if the help text is simply out of sync with the rest of the CLI.
• Suggested fix: Standardize the --repo flag help string (ideally from a single shared template) across all commands.

6. --force flag reused for three unrelated meanings

• Affected commands: add -f/--force ("Overwrite existing workflow files without confirmation"), deploy -f/--force (file overwrite) + deploy -y/--yes (org-mode bulk confirmation) simultaneously, and update --force ("force update even if no changes").
• Issue: --force and --yes both express "skip confirmation," but for different sub-concerns, and --force additionally has a third, unrelated meaning in update (bypass no-op detection).
• Suggested fix: Reserve --force strictly for destructive overwrite actions and --yes/-y strictly for prompt auto-accept; document each command's specific semantics explicitly, and avoid reusing --force for "override no-op detection" in update.

7. Top-level --version flag undocumented in Global Options

• Docs says: Global Options table only lists -h/--help, -v/--verbose, --banner.
• Actual CLI: gh-aw --help also lists --version Print the current version as a top-level global flag (in addition to the gh aw version subcommand).
• Suggested fix: Add --version to the Global Options table in cli.md.

---

🟡 Low severity

10 low-severity findings (click to expand)

8. forecast --concurrency flag undocumented

• Docs says (forecast Options list): --days, --period, --sample, --eval, --timeout, --repo/-r, --json/-j.
• Actual CLI: --concurrency int Maximum number of concurrent usage-artifact downloads (0 = use default) is present but missing from docs.
• Suggested fix: Add --concurrency to the documented forecast options.

9. secrets bootstrap --repo short alias -r undocumented

• Docs says: Lists --repo without noting the -r short alias, inconsistent with how other commands document --repo/-r together.
• Actual CLI: -r, --repo string Target repository...
• Suggested fix: Document as --repo/-r for consistency with other commands.

10. project new --help: "Tracker Id" capitalization inconsistent

• Quote: Custom fields (Tracker Id, Worker Workflow, Target Repo, Priority, Size, dates)
• Issue: "Id" should be "ID" per convention used elsewhere in the CLI (e.g. "workflow-id", "run ID").
• Suggested fix: Custom fields (Tracker ID, Worker Workflow, Target Repo, Priority, Size, dates)

11. fix --help numbered list mixes verb tense/form

• Quote: Item 4 "Writes updated files back to disk." vs items 5-8 "Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists.", "Delete old template files...", "Refresh the dispatcher skill..."
• Issue: Inconsistent verb form (present tense "Writes" vs imperative "Delete"/"Refresh") within the same numbered list.
• Suggested fix: Normalize all list items to one consistent verb form (e.g., all imperative: "Write... / Delete... / Delete... / Delete... / Refresh...").

12. --repo (singular) vs --repos (plural glob filter) naming too similar

• Affected commands: deploy, update, upgrade — --repo (single target repo) vs --repos (glob patterns, only used with --org).
• Issue: The two flags differ only by a trailing "s" but represent very different concepts (single target vs. multi-repo glob filter), which is easy to confuse in scripts/docs.
• Suggested fix: Consider renaming --repos to something more distinct, e.g. --repo-filter or --org-repos.

13. Inconsistent boolean negation pattern (--no-X only vs paired --flag/--no-flag)

• Affected commands: add/add-wizard/fix/init/update/upgrade ship negative-only flags like --no-gitattributes, --no-security-scanner, --no-stop-after (implying default true, no positive counterpart). logs instead ships both --firewall and --no-firewall as separate flags, duplicating surface area versus the single-flag pattern used elsewhere.
• Suggested fix: Standardize on a single boolean flag per concept following the Cobra --flag/--no-flag convention; avoid shipping both a positive and negative flag for the same boolean where one flag would suffice.

14. --label (singular, single value) vs strings-typed plural flags elsewhere

• Affected commands: list/status use --label string (single value only) while logs/audit use --artifacts strings (multi-value) and deploy/update/upgrade use --repos strings (multi-value).
• Issue: No indication in the flag name whether multiple labels can be filtered; inconsistent with the strings-typed multi-value pattern used for similar filters elsewhere.
• Suggested fix: If multi-label filtering is ever needed, add a strings-typed --labels flag for consistency; otherwise no action needed, but worth a docs note.

15. -o/--output default value documented inconsistently

• Affected commands: audit/logs document -o, --output string Output directory for generated files (default ".github/aw/logs"), but outcomes shows -o, --output string Output directory for generated files with no default value shown.
• Suggested fix: Ensure all -o/--output flags document their default value consistently (or confirm outcomes has no default and note that explicitly).

16. logs --last duplicates --count/-c

• Quote: -c, --count int Maximum number of matching workflow runs to return...(default 10) and --last int Alias for --count/-c: number of recent runs to download.
• Issue: Two flags providing identical behavior in the same command is redundant flag surface not seen in similar commands (forecast --sample, health --days).
• Suggested fix: Consider deprecating --last in favor of --count/-c, or clearly mark it as a deprecated alias in the help text (it is already called an "Alias" but could be marked deprecated).

17. remove lacks a confirmation-skip flag present on similar destructive commands

• Affected command: remove (deletes workflow files) only exposes --dir, --no-remove-orphans — no -f/--force or -y/--yes, unlike add/deploy/new (-f/--force) or trial/update/upgrade/deploy (-y/--yes).
• Suggested fix: Consider adding a confirmation-skip flag to remove for consistency, or explicitly document that remove is always non-interactive by design.

---

Inspection metadata

• Commands inspected: all top-level gh-aw commands (add, add-wizard, audit, checks, compile, completion, deploy, disable, doctor, domains, enable, env, experiments, fix, forecast, hash-frontmatter, health, init, lint, list, logs, mcp, mcp-server, new, outcomes, pr, project, remove, run, secrets, status, trial, update, upgrade, validate, version) plus subcommands of env, mcp, secrets, pr, project.
• Date: 2026-07-29
• Method: Built the gh-aw binary from the repo source, collected --help output for every command/subcommand (~2200 lines total), then ran three focused analysis passes (typo/grammar extraction, docs-vs-help diff against docs/src/content/docs/setup/cli.md, and flag-naming/negation-style consistency) over the captured output.
• Note: No spelling typos, broken examples, or incorrect .github/workflows path references were found; the documentation is largely accurate and in sync with the CLI.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · aut00 · 126.5 AIC · ⊞ 6.2K · ◷

• expires on Jul 31, 2026, 5:53 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

I identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 1.56 AIC · ⌖ 6.43 AIC · ⊞ 7.2K · ◷