From 859046878944bae889f01c9191eb66d390af79d7 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Sat, 9 May 2026 07:50:32 +0000 Subject: [PATCH 1/2] docs: update aspire resource command with named options and command-specific help Documents the new named option support for resource command inputs: - Named options (--option-name) instead of positional values - Command-specific --help output showing input types, defaults, and allowed values - Using -- separator to avoid option name collisions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../cli/commands/aspire-resource.mdx | 70 ++++++++++++++++++- 1 file changed, 68 insertions(+), 2 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx index 0defa4115..44a2cff9d 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx @@ -1,6 +1,6 @@ --- title: aspire resource command -description: Learn about the aspire resource command and its usage. This command executes a command on a resource in a running apphost. +description: Learn about the aspire resource command and its usage. This command executes a command on a resource in a running apphost, with support for named command options and command-specific help. --- import Include from '@components/Include.astro'; @@ -13,7 +13,8 @@ import { Aside, Steps } from '@astrojs/starlight/components'; ## Synopsis ```bash title="Aspire CLI" -aspire resource [options] +aspire resource [command-options] [options] +aspire resource -- [command-options] ``` ## Description @@ -30,6 +31,47 @@ selected resource at runtime. This is why the CLI reference documents `aspire resource start`. +### Command inputs as named options + +When a resource command defines inputs (parameters), those inputs are passed as **named options** on the command line — not as positional values. Named options make it easier to supply only the inputs you need, skip optional ones, and pass values in any order. + +To see what inputs a specific command accepts, use the command-specific `--help` flag: + +```bash title="Aspire CLI" +aspire resource --help +``` + +The help output lists each input with its type, whether it's required, its default value (if any), and the set of allowed values for choice inputs. For example: + +```console +Common dashboard/API command with text, number, boolean, choice, and secret argument inputs. + +Usage: + aspire resource argument-commands echo-arguments [command-options] [options] + aspire resource argument-commands echo-arguments -- [command-options] + +Command options: + --message Text value to echo. Required. + --repeat How many times to echo the message. Default: 1. + --shout Uppercase the echoed message. Default: false. + --flavor Choice argument used to verify select input rendering. Allowed values: vanilla, chocolate, strawberry. Default: vanilla. + --secret Secret text input. The command only returns its length. + +Options: + --apphost The path to the Aspire AppHost project file or a directory to search + -?, -h, --help Show help and usage information +``` + +#### Handling option name collisions + +If a command input name conflicts with an Aspire CLI option (such as `--apphost`), use `--` to separate Aspire CLI options from command-specific options: + +```bash title="Aspire CLI" +aspire resource --apphost './MyApp.AppHost.csproj' -- --apphost myvalue +``` + +Everything after `--` is treated as command input options and is not parsed as Aspire CLI flags. + When executed without the `--apphost` option, the command: @@ -89,6 +131,30 @@ The following options are available: aspire resource api restart --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` +- Show command-specific help for a resource command with inputs: + + ```bash title="Aspire CLI" + aspire resource my-resource echo-message --help + ``` + +- Execute a resource command with named inputs: + + ```bash title="Aspire CLI" + aspire resource my-resource echo-message --message "hello" --repeat 3 --shout true + ``` + +- Supply only some optional inputs (skipping others): + + ```bash title="Aspire CLI" + aspire resource my-resource echo-message --message "hello" --flavor chocolate + ``` + +- Use `--` to avoid conflict with an Aspire CLI option named `--apphost`: + + ```bash title="Aspire CLI" + aspire resource my-resource custom-cmd --apphost './MyApp.AppHost.csproj' -- --apphost myvalue + ``` + ## See also - [aspire describe](../aspire-describe/) From 250e98449a264624275760f5c626ef123bf355ce Mon Sep 17 00:00:00 2001 From: David Fowler Date: Sun, 10 May 2026 23:54:55 -0700 Subject: [PATCH 2/2] docs: address aspire resource review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../cli/commands/aspire-resource.mdx | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx index 44a2cff9d..129c70bf6 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx @@ -1,6 +1,6 @@ --- title: aspire resource command -description: Learn about the aspire resource command and its usage. This command executes a command on a resource in a running apphost, with support for named command options and command-specific help. +description: Learn about the aspire resource command and its usage. This command executes a command on a resource in a running apphost. --- import Include from '@components/Include.astro'; @@ -31,46 +31,46 @@ selected resource at runtime. This is why the CLI reference documents `aspire resource start`. -### Command inputs as named options +### Command arguments as named options -When a resource command defines inputs (parameters), those inputs are passed as **named options** on the command line — not as positional values. Named options make it easier to supply only the inputs you need, skip optional ones, and pass values in any order. +When a resource command defines arguments, those arguments are passed as **named options** on the command line. Named options make it easier to supply only the arguments you need, skip optional ones, and pass values in any order. -To see what inputs a specific command accepts, use the command-specific `--help` flag: +To see what arguments a specific command accepts, use the command-specific `--help` flag: ```bash title="Aspire CLI" aspire resource --help ``` -The help output lists each input with its type, whether it's required, its default value (if any), and the set of allowed values for choice inputs. For example: +The help output lists each argument with its type, whether it's required, its default value (if any), and the set of allowed values for choice arguments. For example: ```console -Common dashboard/API command with text, number, boolean, choice, and secret argument inputs. +Echo a message with text, number, boolean, choice, and secret command arguments. Usage: - aspire resource argument-commands echo-arguments [command-options] [options] - aspire resource argument-commands echo-arguments -- [command-options] + aspire resource [command-options] [options] + aspire resource -- [command-options] Command options: --message Text value to echo. Required. --repeat How many times to echo the message. Default: 1. --shout Uppercase the echoed message. Default: false. - --flavor Choice argument used to verify select input rendering. Allowed values: vanilla, chocolate, strawberry. Default: vanilla. - --secret Secret text input. The command only returns its length. + --flavor The message flavor. Allowed values: vanilla, chocolate, strawberry. Default: vanilla. + --secret Secret text command argument. The command only returns its length. Options: - --apphost The path to the Aspire AppHost project file or a directory to search + --apphost The path to the Aspire AppHost file or a directory to search -?, -h, --help Show help and usage information ``` #### Handling option name collisions -If a command input name conflicts with an Aspire CLI option (such as `--apphost`), use `--` to separate Aspire CLI options from command-specific options: +If a command argument name conflicts with an Aspire CLI option (such as `--apphost`), use `--` to separate Aspire CLI options from command-specific options: ```bash title="Aspire CLI" -aspire resource --apphost './MyApp.AppHost.csproj' -- --apphost myvalue +aspire resource --apphost './MyApp.AppHost.cs' -- --apphost myvalue ``` -Everything after `--` is treated as command input options and is not parsed as Aspire CLI flags. +Everything after `--` is treated as command argument options and is not parsed as Aspire CLI flags. When executed without the `--apphost` option, the command: @@ -97,7 +97,9 @@ When executed without the `--apphost` option, the command: The following options are available: -- +- **`--apphost `** + + The path to the Aspire AppHost file or a directory to search. - @@ -125,25 +127,25 @@ The following options are available: aspire resource worker stop ``` -- Target a specific AppHost project: +- Target a specific AppHost file: ```bash title="Aspire CLI" - aspire resource api restart --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' + aspire resource api restart --apphost './src/MyApp.AppHost/AppHost.cs' ``` -- Show command-specific help for a resource command with inputs: +- Show command-specific help for a resource command with arguments: ```bash title="Aspire CLI" aspire resource my-resource echo-message --help ``` -- Execute a resource command with named inputs: +- Execute a resource command with named arguments: ```bash title="Aspire CLI" aspire resource my-resource echo-message --message "hello" --repeat 3 --shout true ``` -- Supply only some optional inputs (skipping others): +- Supply only some optional command arguments (skipping others): ```bash title="Aspire CLI" aspire resource my-resource echo-message --message "hello" --flavor chocolate @@ -152,7 +154,7 @@ The following options are available: - Use `--` to avoid conflict with an Aspire CLI option named `--apphost`: ```bash title="Aspire CLI" - aspire resource my-resource custom-cmd --apphost './MyApp.AppHost.csproj' -- --apphost myvalue + aspire resource my-resource custom-cmd --apphost './apphost.ts' -- --apphost myvalue ``` ## See also