[cli-consistency] CLI Consistency Issues - 2026-04-20

[github-actions]

Summary

Automated CLI consistency inspection found 6 inconsistencies in command help text and documentation that should be addressed for better user experience and documentation clarity.

Breakdown by Severity

• High: 1 (Breaks flag convention)
• Medium: 3 (Inconsistent/misleading)
• Low: 2 (Minor inconsistencies)

Issue Categories

1. Reserved short flag collision (1 command)

   • -o is used for --owner instead of --output
   • Affects: project new

2. Documentation vs CLI mismatch (1 command)

   • Docs incorrectly describe init as interactive
   • Affects: init

3. Inconsistent capitalization (1 flag)

   • Transport option Docker is capitalized unlike stdio/http
   • Affects: mcp add --transport

4. Invalid documentation example (1 command)

   • Example workflow spec does not meet format requirements
   • Affects: add

5. Missing documentation (1 flag)

   • --last alias undocumented
   • Affects: logs

6. Minor style inconsistency (1 flag)

   • Mixed quote style in flag description
   • Affects: compile

Inspection Details

• Total Commands Inspected: 30 (--help run for every command and subcommand)
• Commands with Issues: 6
• Date: 2026-04-20
• Method: Built binary with make build, executed all CLI commands with --help, compared against docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• Flag consistency for --repo, --dir, --engine, --json, --verbose
• Help flag descriptions (Show help for gh aw <command>) — all consistent
• --approve flag text — identical across compile, run, upgrade
• --repeat flag semantics — consistent between run and trial
• Subcommand structure and Available Commands listings
• Global flags (--banner, --verbose, --help) — present on all commands

⚠️ Issues found:

• Reserved short flag -o reused for non-output purpose
• init documentation incorrectly describes interactive behavior
• Capitalization inconsistency in mcp add --transport values
• Invalid workflow spec in add documentation example
• --last flag undocumented in logs options list
• Single-quote vs double-quote style in compile --schedule-seed description

Detailed Findings

1. project new Uses Reserved -o Short Flag for --owner

Command Affected: gh aw project new
Priority: High
Type: Reserved short flag collision

Current Output (from running ./gh-aw project new --help):

  -o, --owner string         Project owner: '`@me`' for current user or organization name (required)

Source (pkg/cli/project_command.go:107):

cmd.Flags().StringP("owner", "o", "", "Project owner: '`@me`' for current user or organization name (required)")

Issue: The AGENTS.md documents -o as a reserved short flag for --output. Every other command in the CLI that has output-directory functionality uses -o for --output (e.g., audit -o, logs -o). Using -o for --owner breaks this convention and may confuse users switching between commands.

Suggested Fix: Change the short flag for --owner to -O (uppercase) or remove the short form entirely, since --owner is required and typically typed in full. The -o short flag should remain reserved for output-related flags per CLI convention.

---

2. init Documentation Claims Interactive Mode — CLI Says Non-Interactive

Command Affected: gh aw init
Priority: Medium
Type: Documentation mismatch

Current CLI Output (from running ./gh-aw init --help):

This command performs non-interactive repository setup and does not prompt for
engine selection or secret configuration.

Documentation (docs/src/content/docs/setup/cli.md):

#### `init`

Initialize repository for agentic workflows. ... Without arguments, enters interactive mode
for engine selection and secret configuration.

```bash
gh aw init                              # Interactive mode: select engine and configure secrets

**Issue**: The documentation says `gh aw init` is "Interactive mode" and "enters interactive mode for engine selection and secret configuration", but the actual CLI help text explicitly says it is non-interactive and does NOT prompt for engine selection or secret configuration. Users following the documentation will be surprised that `init` doesn't prompt them interactively. The interactive wizard for adding workflows is `add-wizard`, not `init`.

**Suggested Fix**: Update `docs/src/content/docs/setup/cli.md` to reflect the actual non-interactive behavior:

gh aw init # Non-interactive repository setup

And update the description: "Initialize repository for agentic workflows (non-interactive). For interactive engine and secret setup, use `add-wizard`."

---

### 3. `mcp add --transport` Inconsistent Capitalization of `Docker`

**Command Affected**: `gh aw mcp add`
**Priority**: Medium
**Type**: Inconsistent capitalization

**Current Output** (from running `./gh-aw mcp add --help`):

  --transport string   Preferred transport type (stdio, http, Docker)

**Source** (`pkg/cli/mcp_add.go:364`):
```go
cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, http, Docker)")

Issue: The transport values list uses Docker (capitalized) while stdio and http are lowercase. The internal error message in the same file (line 179) uses lowercase docker:

return nil, fmt.Errorf("unsupported transport type: %s (supported: stdio, http, docker)", preferredTransport)

This creates a visual inconsistency and may confuse users about the accepted value format.

Suggested Fix: Change the flag description to use consistent lowercase: "Preferred transport type (stdio, http, docker)". Also verify that the flag accepts case-insensitive input or normalize the accepted values.

---

4. add Documentation Contains Invalid Workflow Spec Example

Command Affected: gh aw add
Priority: Medium
Type: Invalid documentation example

Current Documentation (docs/src/content/docs/setup/cli.md):

gh aw add ci-doctor --dir shared                  # Organize in subdirectory

CLI Workflow Spec Requirements (from ./gh-aw add --help):

Workflow specifications:
  - Three parts: "owner/repo/workflow-name[`@version`]" (implicitly looks in workflows/ directory)
  - Four+ parts: "owner/repo/workflows/workflow-name.md[`@version`]" (requires explicit .md extension)
  - GitHub URL: "https://github.com/owner/repo/blob/branch/path/to/workflow.md"
  - Local file: "./path/to/workflow.md" (adds a workflow from local filesystem)
  - Local wildcard: "./*.md" or "./dir/*.md" (adds all .md files matching pattern)

Issue: The example gh aw add ci-doctor --dir shared uses ci-doctor as the workflow spec, which is only 1 part. The CLI requires at minimum a 3-part format (owner/repo/workflow-name) for remote workflows or a ./ prefix for local files. This example would fail in practice.

Suggested Fix: Update the docs example to use a valid 3-part spec:

gh aw add githubnext/agentics/ci-doctor --dir .github/workflows/shared  # Organize in subdirectory

---

5. logs --last Flag Missing from Documentation Options List

Command Affected: gh aw logs
Priority: Low
Type: Missing documentation

Current CLI Output (from running ./gh-aw logs --help):

      --last int              Alias for --count: number of recent runs to download

Documentation (docs/src/content/docs/setup/cli.md options list):

**Options:** `-c`, `--count`, `-e`, `--engine`, `--start-date`, `--end-date`, `--ref`, `--parse`, `--json`, `--train`, `--repo`, `--firewall`, `--no-firewall`, `--safe-output`, `--filtered-integrity`, `--after-run-id`, `--before-run-id`, `--no-staged`, `--tool-graph`, `--timeout`

Issue: The --last flag (alias for --count) exists in the CLI but is not listed in the documentation's options list. Users who prefer --last over --count won't know it's available from the docs.

Suggested Fix: Add --last to the options list: **Options:** ..., --last, --count, ...

---

6. compile --schedule-seed Uses Single Quotes Where Other Flags Use Double Quotes

Command Affected: gh aw compile
Priority: Low
Type: Minor style inconsistency

Current Output (from running ./gh-aw compile --help):

      --schedule-seed string        Override the repository slug (owner/repo) used as seed for fuzzy schedule scattering (e.g. 'github/gh-aw'). ...

Issue: The --schedule-seed flag description uses single quotes for the example value ('github/gh-aw'), while most other flag descriptions and examples in the CLI use double quotes (e.g., --stop-after string Override stop-after value in the workflow (e.g., '+48h', '2025-12-31 23:59:59')). Actually, looking more broadly, the stop-after also uses single quotes. However many inline examples elsewhere use no quotes. This is a very minor stylistic inconsistency that doesn't affect functionality.

Suggested Fix: Standardize quote style in flag descriptions. If single quotes are preferred in flag descriptions (as seen in --stop-after), ensure all flag descriptions use single quotes for example values consistently.

Generated by CLI Consistency Checker · ● 1.4M · ◷

• expires on Apr 22, 2026, 1:50 PM UTC

[github-actions]

🍪 *Issue Monster selected this for Copilotecho BEGIN___COMMAND_OUTPUT_MARKER ; PS1= ; PS2= ; unset HISTFILE ; EC=0 ; echo ___BEGIN___COMMAND_DONE_MARKER___0 ; }

I've 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! 🍪> [!CAUTION]

Security scanning requires review for Issue Monster

Details

Potential security threats were detected in the agent output. The workflow output should be reviewed before merging.

Review the workflow run logs for details.

🍪 Om nom nom by Issue Monster · ● 27.4K · ◷