microsoft / microsoft/aspire.dev

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

Open Beginner friendly
#1,463 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.