[cli-consistency] CLI Consistency Issues - 2026-09-11

[github-actions]

Summary

Automated inspection of gh aw CLI help output (/tmp/gh-aw/agent/all-help.txt, generated from run 34603722663) against the CLI's own generated help text and docs/src/content/docs/setup/cli.md. Found 2 issues: 1 medium-severity factual bug in generated help text, 1 low-severity structural inconsistency between related parent commands.

Severity breakdown: 🟠 Medium: 1 · ⚪ Low: 1

---

🟠 Medium — gh aw edit --help references a --no-merge flag that does not exist on edit

Affected command: gh aw edit

Location: pkg/cli/edit_command.go line 29

Exact CLI output (from help-output/edit.txt):

Experimental: edit schema-validated workflow frontmatter and recompile its generated file.

The workflow-id may be a workflow name, a Markdown filename, or a path. Changes are
validated before writing. Workflows managed by a source: declaration can be edited
locally; by default, future updates will merge in those local changes (use --no-merge to override).

But the Flags: section of gh aw edit --help has no --no-merge flag:

Flags:
      --add stringArray             Append a value to a list (path=value)
      --add-import stringArray      Append a workflow import path
      --add-skill stringArray       Append a workflow skill
  -d, --dir string                  Workflow directory (default: $GH_AW_WORKFLOWS_DIR or .github/workflows)
      --dry-run                     Validate changes without writing or compiling
  -h, --help                        Show help for gh aw edit
      --remove stringArray          Remove a value from a list (path=value)
      --remove-import stringArray   Remove a workflow import path
      --remove-skill stringArray    Remove a workflow skill
      --schedule string             Set a schedule using a fuzzy schedule or cron expression; use off to remove it
      --set stringArray             Set a frontmatter path (path=value)
      --unset stringArray           Remove a frontmatter path

Expected vs actual: The --no-merge flag actually belongs to gh aw update (pkg/cli/update_command.go line 36: Use --no-merge to override local changes with the upstream version.), which performs the 3-way merge on source:-managed workflows. gh aw edit itself has no merge/override behavior or flag — it edits frontmatter directly and has nothing named --no-merge. A user reading edit --help and trying gh aw edit <workflow> --no-merge ... will get an "unknown flag" error.

Suggested fix: Update the Long description in pkg/cli/edit_command.go to either remove the --no-merge reference or rephrase it to point to the correct command, e.g.:

"...locally; running gh aw update afterward merges those local changes into the upstream version by default (use gh aw update --no-merge to override)."

Priority: Medium — misleading help text that references a nonexistent flag on the command being described.

---

⚪ Low — gh aw project help Usage: block omits [flags] form, unlike sibling parent commands

Affected command: gh aw project

Location: pkg/cli/project_command.go (NewProjectCommand, no RunE set on the parent command)

Exact CLI output (help-output/project.txt):

Usage:
  gh aw project [command]

Compare with other subcommand-only parent commands (mcp, secrets, pr, env), which all show both forms:

Usage:
  gh aw mcp [flags]
  gh aw mcp [command]

Usage:
  gh aw secrets [flags]
  gh aw secrets [command]

Usage:
  gh aw pr [flags]
  gh aw pr [command]

Usage:
  gh aw env [flags]
  gh aw env [command]

Expected vs actual: mcp, secrets, pr, and env all define a RunE on the parent cobra command (even if it just prints help or basic info), which causes cobra to render [flags] in Usage. project (pkg/cli/project_command.go) has no RunE on the parent, so cobra only shows [command]. This is a minor structural/stylistic inconsistency across otherwise-parallel "namespace" commands (all group related subcommands: new, list, set, get/update, transfer, etc.).

Suggested fix: Either add a no-op RunE to NewProjectCommand (matching the pattern used by mcp/secrets/pr/env) for consistent Usage output, or intentionally leave as-is if the maintainers prefer minimal parent commands with only subcommands — in which case no fix is needed, but worth a decision to standardize going forward.

Priority: Low — purely cosmetic; does not affect functionality since gh aw project new ... works correctly either way.

---

Areas checked with no issues found

• Global flag consistency (--banner, -v/--verbose, -h/--help) — consistent across all ~40 commands.
• -r/--repo, -j/--json, -d/--dir, -e/--engine short-flag pairings — consistent across all commands that expose them.
• --no-gitattributes, --no-security-scanner, --no-stop-after/--stop-after flag text — identical wording across add, add-wizard, deploy, update, trial.
• --approve flag description — identical wording across run, compile, update, upgrade.
• Typo/grammar scan (common misspellings, "Github" capitalization, double-spacing) — none found in help text.
• docs/src/content/docs/setup/cli.md command list (37 documented commands/subsections) matches the command list in gh aw --help.
• add-wizard docs "Options:" line matches actual flags including --no-config.
• doctor/env intentionally restrict --repo to bare owner/repo (no [HOST/] prefix) and this is documented consistently in both CLI help and cli.md; not a bug.
• Command examples in compile, validate, run, trial, list, domains, checks help text were spot-checked for plausible flag combinations and file-path correctness (.github/workflows) — all correct.

---

Inspection metadata

• Commands inspected: All ~37 top-level/subcommands from gh aw --help, cross-referenced with /tmp/gh-aw/agent/help-output/*.txt (per-command help dumps) and /tmp/gh-aw/agent/all-help.txt (~26,267 lines).
• Method: Automated grep/diff scan for typo patterns, flag-naming consistency across commands, cross-checking flag references embedded in Long/description text against each command's actual Flags: section, and comparing CLI output against docs/src/content/docs/setup/cli.md.
• Date: 2026-09-11
• Source run: github/gh-aw run 34603722663

Generated by ✅ CLI Consistency Checker · copilot · auto · 83.4 AIC · ⌖ 7.74 AIC · ⊞ 7.4K · ◷

• expires on Sep 13, 2026, 5:32 AM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-09-13T13:32:17.974Z.

Closed by Workflow