Standardize CLI argument syntax for consistency

[Copilot]

The CLI used inconsistent notation for command arguments—mixing verbose descriptors like workflow-id-or-file with simpler ones like pattern, making the interface harder to learn and use.

Changes

Simplified argument names across all commands:

• workflow-id → workflow (11 commands: new, enable, disable, compile, run, fix, logs, update, and MCP subcommands)
• workflow-id-or-file → workflow (MCP list/inspect/add)
• mcp-server-name → server (MCP add)
• mcp-server → server (MCP list-tools)
• workflow-id-pattern → pattern (remove command)
• run-id-or-url → run-id (audit command)
• pull-request-url → pr-url (PR transfer)
• id → campaign-id (campaign new)

Added validation tests to enforce consistency:

• Argument syntax patterns match Cobra validators
• Naming conventions follow established patterns
• Bracket usage aligns with optionality (<required> vs [optional])

Example

Before:

gh aw compile [workflow-id]...
gh aw run <workflow-id>...
gh aw mcp list [workflow-id-or-file]
gh aw mcp list-tools <mcp-server> [workflow-id-or-file]

After:

gh aw compile [workflow]...
gh aw run <workflow>...
gh aw mcp list [workflow]
gh aw mcp list-tools <server> [workflow]

All functionality remains unchanged—only the displayed syntax in help text is clearer.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[cli-consistency] Inconsistent argument syntax: optional vs required</issue_title>
<issue_description>## Issue Description

Commands: Multiple
Type: Inconsistent argument syntax notation
Priority: Low

Issue

The CLI uses inconsistent notation for command arguments across different commands, which could confuse users about whether arguments are optional or required.

Examples

Square brackets [] for optional:

Use:   "new [workflow-id]",           // Optional
Use:   "remove [workflow-id-pattern]", // Optional
Use:   "enable [workflow-id]...",     // Optional (multiple)
Use:   "disable [workflow-id]...",    // Optional (multiple)
Use:   "compile [workflow-id]...",    // Optional (multiple)
Use:   "logs [workflow-id]",          // Optional
Use:   "update [workflow-id]...",     // Optional (multiple)
Use:   "fix [workflow-id]...",        // Optional (multiple)

Angle brackets <> for required:

Use:   "run (workflow-id)...",        // Required (multiple)
Use:   "add (workflow)...",           // Required
Use:   "audit (run-id-or-url)",      // Required
Use:   "trial (workflow-spec)...",   // Required

Mixed patterns in MCP subcommands:

Use:   "list [workflow-id-or-file]",                    // Optional
Use:   "inspect [workflow-id-or-file]",                // Optional
Use:   "list-tools (mcp-server) [workflow-id-or-file]", // Mixed: required + optional
Use:   "add [workflow-id-or-file] [mcp-server-name]",  // Both optional

PR subcommand:

Use:   "transfer (pull-request-url)",  // Required

Campaign subcommands:

Use:   "campaign [filter]",    // Optional
Use:   "status [filter]",      // Optional  
Use:   "new (id)",             // Required

Current Behavior

The current implementation is technically correct - the brackets indicate the actual optionality of arguments as enforced by Cobra's Args validators (e.g., cobra.MinimumNArgs(1), cobra.MaximumNArgs(1), cobra.ExactArgs(1)).

Consistency Recommendation

While technically correct, the notation is inconsistent in visual pattern. Consider:

1. Keep current approach (mixed notation based on actual optionality) - Most precise
2. Standardize on descriptive names - Use clearer parameter names like (required-id) vs [optional-id]
3. Add help text clarification - Ensure Long descriptions clearly state when arguments are required

Suggested Fix

Option 1: Add clarifying text to help

For commands with optional arguments, add a note in the Long description:

If no workflow is specified, all workflows will be processed.

Option 2: Make argument names more descriptive

Use:   "compile [workflow...]",       // Makes it clear workflow is optional
Use:   "run (workflow...)",           // Makes it clear workflow is required

This is a low priority issue as the current behavior is correct, but consistency improvements would enhance user experience.

AI generated by CLI Consistency Checker

Comments on the Issue (you are @copilot in this section)

• Fixes [cli-consistency] Inconsistent argument syntax: optional vs required #7247

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.