Required vs optional arguments are clear

deploy target env tells the user nothing about which argument is required, which is optional, or what the default is. They guess, hit an error, guess again, and eventually give up. Unclear argument signatures also break automated documentation and API-shaped wrappers that parse help output. When a missing required argument triggers a stack trace instead of Error: missing argument <target>, users interpret the tool as unstable and stop using it in CI.

Use angle brackets for required arguments and square brackets for optional ones in command signatures, and pass show_default=True (or equivalent) so defaults appear in --help. In src/cli/commands/deploy.ts:

program
  .command('deploy <target> [environment]')
  .description('Deploy to target (environment defaults to production)')
  .option('-p, --port <number>', 'Port to use', '3000')

• ID: cli-quality.command-structure.arg-clarity

• Severity: medium

• What to look for: Enumerate every required and optional argument across all commands. For each argument, examine help text for each command. Check that required arguments are clearly marked (angle brackets <required> in commander/cobra, or documented as required). Check that optional arguments are marked (square brackets [optional] in commander/cobra, or documented as optional). Verify that default values for optional arguments are shown in help text.

• Pass criteria: Help text distinguishes required from optional arguments using standard notation (<required> vs [optional]) or clear labeling. Default values are shown for options that have them. Running a command without a required argument produces a clear error (not a crash or silent failure) — 100% of arguments must have descriptive help text of at least 5 words. Report: "X arguments found, all Y have descriptions in help text."

• Fail criteria: Help text does not distinguish required from optional arguments, or default values are not shown, or missing required arguments cause a crash or unhelpful error instead of a usage hint.

• Skip (N/A) when: The CLI has no arguments or options (only bare commands like mytool start). All checks skip when no CLI entry point is detected.

• Detail on fail: "'deploy' command shows 'deploy target env' — unclear which args are required. Should be 'deploy <target> [env]'" or "Default value for --port not shown in help text — user must read source to know it defaults to 3000"

• Remediation: Clear argument labeling prevents user confusion and support requests:

  // commander — angle brackets = required, square brackets = optional
  program
    .command('deploy <target> [environment]')
    .description('Deploy to target (environment defaults to "production")')
    .option('-p, --port <number>', 'Port to use (default: 3000)', '3000')
    .action(deploy)
  

  # click — required by default, use default= for optional
  @cli.command()
  @click.argument('target')  # required
  @click.argument('environment', default='production')  # optional with default
  @click.option('--port', default=3000, show_default=True, help='Port to use')
  def deploy(target, environment, port):
      """Deploy to TARGET in the specified ENVIRONMENT."""
      pass