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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0
• Medium: 1 (inconsistent terminology in the same command's help)
• Low: 4 (missing examples for flags, vague comment)

Inspection Details

• Total Commands Inspected: 30
• Commands with Issues: 4
• Date: 2026-04-23
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming and short-flag consistency across commands
• Global flags (--banner, -v/--verbose, -h/--help) present on all commands
• Engine name consistency (copilot, claude, codex, gemini, crush) throughout
• --repo/-r flag consistency on relevant commands
• --json/-j flag consistency on data-returning commands
• --dir/-d flag consistency on directory-accepting commands
• Help text style and capitalization
• Terminology ("workflow-id", "lock file", "frontmatter") used consistently

⚠️ Issues found:

• Inconsistent terminology within pr transfer help
• Vague inline comment in mcp-server examples
• Missing examples for logs --train, logs --no-staged, trial --trigger-context

Detailed Findings

1. Inconsistent Terminology in pr transfer Help

Command Affected: gh aw pr transfer
Priority: Medium
Type: Inconsistent terminology within same command

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

Transfer a pull request from one repository to another.

This command fetches the pull request details, applies the changes as a single commit,
and creates a new pull request...

The command will:
1. Fetch the PR details (title, body, changes)
2. Apply changes as a single squashed commit
3. Create a new PR in the target repository
4. Copy the original title and description

Issue: The opening description says "applies the changes as a single commit" but the numbered list below says "Apply changes as a single squashed commit". The word "squashed" is missing from the first reference, making it inconsistent within the same help page.

Suggested Fix: Update the opening description to match the numbered list:

This command fetches the pull request details, applies the changes as a single squashed commit,
and creates a new pull request...

---

2. Vague Example Comment in mcp-server

Command Affected: gh aw mcp-server
Priority: Low
Type: Unclear comment

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

  DEBUG=mcp:* GITHUB_ACTOR=octocat gh aw mcp-server    # Run with verbose logging and actor

Issue: The comment "Run with verbose logging and actor" is vague — "and actor" doesn't explain what effect GITHUB_ACTOR has. The preceding paragraph explains it enables access control, so the comment should reflect that.

Suggested Fix:

  DEBUG=mcp:* GITHUB_ACTOR=octocat gh aw mcp-server    # Run with verbose logging and actor-based access control

---

3. Missing Examples for logs --train and logs --no-staged Flags

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

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

• --train: "Train Drain3 (log template mining) weights from downloaded runs and write drain3_weights.json to the output directory" — no example in the examples section
• --no-staged: "Filter out staged workflow runs" — no example in the examples section; also "staged" workflow runs is not explained anywhere in the help

Issue: All other filters in gh aw logs have examples (e.g., --engine, --firewall, --safe-output, --ref, --after-run-id). The --train and --no-staged flags lack examples, and --no-staged doesn't explain what "staged" means.

Suggested Fix: Add examples and clarify:

  gh aw logs --no-staged               # Exclude staged (trial/dry-run) workflow runs
  gh aw logs --train                   # Download runs and train Drain3 log templates

---

4. Missing Example for trial --trigger-context Flag

Command Affected: gh aw trial
Priority: Low
Type: Missing documentation example

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

• --trigger-context string: "Trigger context URL (e.g., GitHub issue URL) for issue-triggered workflows" — no example in the examples section

Issue: The flag has a parenthetical usage hint in the description but no corresponding example showing the full command, unlike other flags in this command (e.g., --host-repo, --clone-repo, --repeat, --auto-merge-prs).

Suggested Fix: Add an example:

  gh aw trial githubnext/agentics/my-workflow --trigger-context https://github.com/owner/repo/issues/42  # Run with issue context

Generated by CLI Consistency Checker · ● 799.6K · ◷

• expires on Apr 25, 2026, 1:48 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 · ● 17.9K · ◷