microsoft / microsoft/aspire.dev
Docs: custom resource command CLI arguments are named options (--flags), not positional
Nobody has claimed this yet.
- Dominant language
- MDX
- Stars
- 193
- Forks
- 87
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 73
Description
### Page
[`fundamentals/custom-resource-commands`](https://aspire.dev/fundamentals/custom-resource-commands/) → "Command arguments" / "Pass arguments from the CLI"
Source: [`custom-resource-commands.mdx`](https://github.com/microsoft/aspire.dev/blob/release/13.5/src/frontend/src/content/docs/fundamentals/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":
```bash
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](https://github.com/microsoft/aspire/blob/cfbf1c432e94dfe4a3261593eeef8c93913079bb/src/Aspire.Cli/Commands/ResourceCommand.cs#L383-L408). 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 '--' 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
```bash
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 `--` 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`.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with src/frontend/src/content/docs/fundamentals/custom-resource-commands.mdx, focusing on the “Command arguments” and “Pass arguments from the CLI” sections, then compare the behavior with ResourceCommand.cs lines 383-408. Update the CLI behavior descriptions and examples to use named options, aliases, and the required-option error, and verify that no positional-argument wording remains.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 84/100