Docs: custom resource command CLI arguments are named options (--flags), not positional

[IEvangelist]

Page

fundamentals/custom-resource-commands → "Command arguments" / "Pass arguments from the CLI"

Source: custom-resource-commands.mdx

Problem

The page repeatedly states custom resource command arguments are passed on the CLI as ordered positional values:

• "Commands can declare input arguments that ... the CLI accepts as ordered positional values."
• InteractionInput InputType table → CLI behavior column: "Positional string value".
• "Pass arguments from the CLI ... supply argument values as ordered positional tokens after the command name":

aspire resource myservice send-message "Hello world" 3 --apphost MyApp.AppHost.csproj

""Hello world" maps to the first argument (text) and 3 maps to the second (repeat)."

But the CLI exposes these inputs as named options (--flags), not positional — see ResourceCommand.cs L383-408. Each declared input becomes new Option<...>($"--{optionName}") (exposed as both exact-name and kebab-case). Leftover positional tokens are explicitly not bound:

"Metadata-backed command inputs are options only. Any leftover token is forwarded as an unknown argument name so hosting-side validation reports it instead of binding it positionally."

Missing required inputs produce Required option '--<name>' was not provided. So the documented example fails: "Hello world" and 3 are treated as unrecognized tokens rather than mapped to text / repeat.

Correct usage

aspire resource myservice send-message --text "Hello world" --repeat 3 --apphost MyApp.AppHost.csproj

(kebab-case aliases are also accepted, e.g. --log-level for an input named LogLevel.)

Suggested fix

Update the "Command arguments" intro, the InteractionInput CLI behavior column ("Positional string value" / "Positional string parsed as number"), and the "Pass arguments from the CLI" section to show named --<name> options (with kebab-case aliases) and the required-option error, instead of positional tokens.

Provenance

aspire.dev release/13.5 (custom-resource-commands.mdx); aspire release/13.5 (ResourceCommand.cs). Confirmed against the 13.5 candidate CLI 13.5.0-pr.17553.