aspire resource command

Name

aspire resource - Execute a command on a resource.

Synopsis

Aspire CLI

aspire resource <resource> <command> [command-options] [options]
aspire resource <resource> <command> -- [command-options]

Description

The aspire resource command executes a command exposed by a resource in a running AppHost. Use it to trigger actions such as start, stop, or restart without opening the dashboard.

The available command names depend on the selected resource. If a resource doesn’t expose the command you specify, Aspire returns an error.

Заметка

aspire resource doesn’t expose a fixed set of CLI subcommands in --help. Instead, <command> is a positional argument whose valid values come from the selected resource at runtime. This is why the CLI reference documents aspire resource as a single command page instead of separate pages such as aspire resource start.

Command arguments as named options

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 arguments a specific command accepts, use the command-specific --help flag:

Aspire CLI

aspire resource <resource> <command> --help

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:

Echo a message with text, number, boolean, choice, and secret command arguments.

Usage:
  aspire resource <resource> <command> [command-options] [options]
  aspire resource <resource> <command> -- [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    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 file or a directory to search
  -?, -h, --help   Show help and usage information

Handling option name collisions

If a command argument name conflicts with an Aspire CLI option (such as --apphost), use -- to separate Aspire CLI options from command-specific options:

Aspire CLI

aspire resource <resource> <command> --apphost './MyApp.AppHost.cs' -- --apphost myvalue

Everything after -- is treated as command argument options and is not parsed as Aspire CLI flags.

Discovering available resource commands

Running aspire resource <resource> --help with a specific resource name queries the running AppHost and appends an Available resource commands section to the help output. This lets you discover what commands a resource supports without opening the dashboard.

Example output

Available resource commands:
  restart    Restart the resource.
  start      Start the resource.
  stop       Stop the resource.

If no single in-scope AppHost can be determined without an explicit --apphost, the resource-scoped help is shown without the commands section rather than prompting for AppHost selection.

To pass --help as an argument to the resource command itself (rather than as a CLI help flag), separate it with --:

Aspire CLI

aspire resource myresource mycommand -- --help

AppHost selection

When executed without the --apphost option, the command:

1. Scans for all running AppHost processes.
2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target.
3. If only one AppHost is running in scope, connects to it directly.
4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection.

Arguments

• <resource>

  The name of the resource to execute the command on.

• <command>

  The name of the resource command to execute, such as start, stop, restart, set-parameter, or delete-parameter.

Built-in parameter commands

Aspire provides two built-in resource commands for managing parameter resources at runtime. These commands accept named options and can be used non-interactively (for example, in scripts or automation). The examples in this section assume an AppHost parameter resource named mydb-password; for details on defining parameter resources, see External parameters.

Boolean options for these commands require an explicit true or false value. For example, --save-to-user-secrets true requests saving the value to user secrets.

• set-parameter — Set the value of a parameter resource. The legacy name parameter-set is also accepted.

  Option	Description
  --value <value>	Required. The value to assign to the parameter.
  --save-to-user-secrets [true|false]	Optional. Save the value to the .NET user secrets store in addition to the running AppHost. Defaults to preserving any existing saved state.

  Aspire CLI

  aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword"
  aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" --save-to-user-secrets true

• delete-parameter — Delete the current value of a parameter resource. The legacy name parameter-delete is also accepted.

  Option	Description
  --delete-from-user-secrets [true|false]	Optional. Also remove the value from the .NET user secrets store. The value is removed only when this option is supplied with true.

  Aspire CLI

  aspire resource mydb-password delete-parameter
  aspire resource mydb-password delete-parameter --delete-from-user-secrets true

  To see the current options for a parameter command, use command-specific help:

  Aspire CLI

  aspire resource mydb-password set-parameter --help

Заметка

The canonical command names changed in Aspire 13.4. parameter-set was renamed to set-parameter and parameter-delete was renamed to delete-parameter. The old names are accepted as aliases and continue to work.

Options

The following options are available:

• --apphost <apphost>

  The path to the Aspire AppHost file or a directory to search.

• -?, -h, --help

  Prints help and usage documentation for the available commands and options.

• --include-hidden

  Includes resource commands that are marked as hidden. By default, hidden commands are not shown in help output or executed. Use this option to expose and run commands that are intentionally hidden from the default command listing.

• -l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

• --non-interactive

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

• --nologo

  Suppress the startup banner and telemetry notice.

• --banner

  Display the animated Aspire CLI welcome banner.

• --wait-for-debugger

  Wait for a debugger to attach before running a command.

Examples

• Restart a resource in the current AppHost:

  Aspire CLI

  aspire resource cache restart

• Stop a specific resource:

  Aspire CLI

  aspire resource worker stop

• Target a specific AppHost file:

  Aspire CLI

  # C# AppHost
  aspire resource api restart --apphost './apphost.cs'
  
  # TypeScript AppHost
  aspire resource api restart --apphost './apphost.mts'

• List available commands for a specific resource:

  Aspire CLI

  # C# AppHost
  aspire resource myapi --help --apphost './apphost.cs'
  
  # TypeScript AppHost
  aspire resource myapi --help --apphost './apphost.mts'

• Include hidden commands when listing available commands:

  Aspire CLI

  # C# AppHost
  aspire resource myapi --help --include-hidden --apphost './apphost.cs'
  
  # TypeScript AppHost
  aspire resource myapi --help --include-hidden --apphost './apphost.mts'

• Show command-specific help for a resource command with arguments:

  Aspire CLI

  aspire resource my-resource echo-message --help

• Execute a resource command with named arguments:

  Aspire CLI

  aspire resource my-resource echo-message --message "hello" --repeat 3 --shout true

• Supply only some optional command arguments (skipping others):

  Aspire CLI

  aspire resource my-resource echo-message --message "hello" --flavor chocolate

• Use -- to avoid conflict with an Aspire CLI option named --apphost:

  Aspire CLI

  aspire resource my-resource custom-cmd --apphost './apphost.mts' -- --apphost myvalue

See also

• aspire describe
• aspire logs
• aspire wait