aspire do command

Name

aspire do - Execute a specific pipeline step and its dependencies.

Synopsis

Aspire CLI

aspire do <step> [options] [[--] <additional arguments>...]

Description

The aspire do command executes a specific pipeline step and its dependencies in your Aspire AppHost. This command provides fine-grained control over the orchestration pipeline, allowing you to run individual steps of the deployment or build process.

The Aspire CLI uses the following logic, in order, to determine which AppHost project to process:

• The --apphost option.

  This option specifies the path to the Aspire AppHost project file to process.

• The rooted aspire.config.json file.

  If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy .aspire/settings.json files are still read during migration.

• Searches the current directory and subdirectories.

  Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects.

  Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it.

The command allows you to:

• Execute specific pipeline steps without running the entire pipeline
• Run only the dependencies needed for a particular step
• Test individual pipeline stages during development
• Customize pipeline execution with environment-specific settings
• Discover available steps and their dependencies using the diagnostics step

For more information, see Pipelines and app topology.

Arguments

The following arguments are available:

• step

  The name of the step to execute.

Options

The following options are available:

• --

  Delimits arguments to aspire do from arguments for the AppHost. All arguments after this delimiter are passed to the application being run.

• --apphost <apphost>

  The path to the Aspire AppHost project file.

• -o, --output-path

  The optional output path for artifacts.

• --pipeline-log-level

  Set the minimum log level for pipeline logging. Valid values are: trace, debug, information, warning, error, critical. The default is information.

• -e, --environment

  The environment to use for the operation. The default is Production.

• --include-exception-details

  Include exception details (stack traces) in pipeline logs.

• --list-steps

  List the pipeline steps that would be executed, without running them. Useful for inspecting what a pipeline command will do before invoking it for real.

• --no-build

  Don’t build or restore the AppHost project before running the command. Use this when you’ve already built the AppHost (for example, in a CI step) and want to skip the implicit build.

• -?, -h, --help

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

• -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.

Discovering available steps

Before executing a pipeline step, you can discover what steps are available in your application’s pipeline and understand their dependencies. Aspire provides two complementary tools for this:

• aspire do --list-steps — a quick, compact listing of every pipeline step with its direct dependencies and tags. Available on aspire deploy, aspire publish, aspire destroy, and aspire do. Useful for a fast “what would happen?” view before running a command.
• aspire do diagnostics — a verbose, in-depth report. The diagnostics step is itself part of the pipeline, so aspire do diagnostics runs it like any other step.

Quick listing with --list-steps

Running aspire do --list-steps produces a numbered list of every step in the pipeline, what each one depends on, and any tags it carries:

Aspire CLI

aspire do --list-steps

Example output:

Output

1. parameter-prompt
   └─ No dependencies

2. provision-redis-infra
   ├─ Depends on: parameter-prompt
   └─ Tags: provision-infra

3. build-webapi
   ├─ Depends on: parameter-prompt
   └─ Tags: build-compute

4. deploy-webapi
   ├─ Depends on: provision-redis-infra, build-webapi
   └─ Tags: deploy-compute

Each entry shows the step’s position in execution order, the steps it depends on, and any tags it declares. Steps with no dependencies and no tags are shown as └─ No dependencies.

Use this when you just need to confirm a step exists or check its direct dependencies.

In-depth report with aspire do diagnostics

For comprehensive information about your pipeline, run the diagnostics step:

Aspire CLI

aspire do diagnostics

The diagnostics step provides a deeper analysis than --list-steps, including:

• All available steps and their dependencies
• Execution order with parallelization indicators
• Step dependencies and target resources
• Configuration issues like orphaned steps or circular dependencies

This is particularly useful after installing a deployment package or when you want to understand which steps will execute for a given command.

Well-known steps

Aspire provides several well-known steps that serve as entry points for common operations:

• build: Builds container images for compute resources defined in the application
• push: Pushes container images to registries after they have been built
• publish: Generates deployment artifacts by serializing resources to disk
• deploy: Orchestrates the complete deployment process including infrastructure provisioning, image building, and application deployment

Resources in your application can contribute their own custom steps, and you can add application-specific steps through the pipeline API.

Examples

The following examples demonstrate common pipeline operations:

• Quickly list the steps in your pipeline:

  Aspire CLI

  aspire do --list-steps

  This displays a compact view of every step with its dependencies and tags. Use it for a fast “what would happen?” check before running a pipeline command.

• Run the diagnostics step for an in-depth report:

  Aspire CLI

  aspire do diagnostics

  This runs the diagnostics pipeline step, which produces a verbose report with execution order, parallelization, target resources, and configuration issues like orphaned steps or circular dependencies.

• Build container images for your application:

  Aspire CLI

  aspire do build

  This builds all container images for compute resources defined in your AppHost.

• Push container images to a registry:

  Aspire CLI

  aspire do push

  This pushes built container images to their configured registries. The push step automatically includes its dependencies (building images and ensuring registry availability) before pushing.

• Execute a pipeline step with debug logging:

  Aspire CLI

  aspire do deploy --pipeline-log-level debug

  Use debug logging to get detailed troubleshooting output during step execution.

• Execute a pipeline step for a specific environment:

  Aspire CLI

  aspire do publish --environment Staging

  Target different environments to use environment-specific configurations.

• Execute a pipeline step with custom output path:

  Aspire CLI

  aspire do publish --output-path ./artifacts

  Specify where publishing artifacts should be written.

• Execute a pipeline step with additional arguments:

  Aspire CLI

  aspire do test -- --configuration Release

  Pass additional arguments to the AppHost after the -- delimiter.