[cli-consistency] Inconsistent argument syntax: optional vs required

[github-actions]

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