`spawn launch`: `--name` is documented as "required" but is ignored for arg validation — the `--help` "Direct with flags" example fails with `accepts 1 arg(s), received 0`

[scttfrdmn]

Summary

spawn launch requires the spore name as a positional argument, but --help documents a --name flag as "required" and shows a "Direct with flags" example that omits the positional entirely. Following either piece of the built-in documentation produces a hard failure. Both --name and the positional exist, and supplying --name alone does not satisfy Cobra's ExactArgs(1).

The failure message (accepts 1 arg(s), received 0) never mentions name, so from the caller's point of view a launch invocation that matches the documented example fails with an error that points at nothing.

Version

Version:    0.100.0
Git Commit: 6521c239e5f246e4ddb476e5df67e4e58df241e5
Build Date: 2026-08-11T18:51:00Z

Reproduction

The two contradictory pieces of spawn launch --help:

Examples:
  # Direct
  spawn launch --instance-type m7i.large --region us-east-1     <-- no positional

Usage:
  spawn launch <name> [flags]                                   <-- positional required

Flags:
      --name string    Name your spore, required (sets Name tag, DNS, and hostname)

Case A — pass only --name, exactly as the flag help says is required:

$ spawn launch --name biosurf-repro-test --instance-type m7i.large --region us-east-1
accepts 1 arg(s), received 0

Case B — the documented "Direct with flags" example, verbatim from --help:

$ spawn launch --instance-type m7i.large --region us-east-1
accepts 1 arg(s), received 0

Case C — positional supplied, so validation passes and the launch proceeds:

$ spawn launch posname --name flagname --instance-type m7i.large --region us-east-1

⚠️  Auto-setting --idle-timeout=1h to prevent zombie instances
   Instance will terminate after 1 hour of inactivity.

(Case C also raises a second question: when both are given, which one wins for the Name tag, DNS and hostname? That precedence is not documented.)

Why this is worth fixing rather than working around

It is a one-line workaround once you know it, but the cost is paid at exactly the wrong moment. This surfaced in a scripted, tagged, budgeted DFT campaign where each spawn launch is a deliberate, paid action on a large instance. A launcher that rejects its own documented invocation form with an error naming no flag sends the operator looking for a credentials, quota or region problem first. Automation written against --help is broken on the happy path.

Suggested fixes, in preference order

1. Accept either form. If the positional is absent and --name is set, use --name. Replace ExactArgs(1) with MaximumNArgs(1) plus a post-parse check that at least one of the two is present. This makes both documented forms work and is backward compatible.
2. Improve the error regardless of 1. accepts 1 arg(s), received 0 should read something like spawn launch requires a name: spawn launch <name> [flags] (or --name <name>).
3. Make the docs self-consistent. If the positional is the intended interface, fix the # Direct example to include a name and drop "required" from --name's help, or mark --name as an alias for the positional. If both are kept, document precedence.

Notes

• No instance was created by any of the reproduction commands above; case C was interrupted before provisioning, and describe-instances confirmed no new instance in the account.
• Worked around locally by always passing the name positionally: spawn launch <name> --instance-type ... --tag Workstream=... --tag Campaign=..., which works reliably.