Aspire CLI overview

The Aspire CLI (aspire command) is a cross-platform tool that provides command-line functionality to create, manage, run, and publish polyglot Aspire projects. Use the Aspire CLI to streamline development workflows and coordinate services for distributed applications.

Nota

Starting with Aspire 13.0, the Aspire CLI requires .NET SDK version 10.0.100 or later. Ensure that you have the appropriate .NET SDK installed to use the Aspire CLI.

The Aspire CLI is an interactive-first experience.

Install the Aspire CLI Get started by installing the Aspire CLI on your machine.

Review install script reference Explore the details of the install script with reference.

Use templates

The aspire new command is an interactive-first CLI experience, and is used to create one or more Aspire projects. As part of creating a project, Aspire CLI ensures that the latest Aspire project templates are installed into the dotnet system.

Use the aspire new command to create an Aspire project from a list of templates. Once a template is selected, the name of the project is set, and the output folder is chosen, aspire downloads the latest templates and generates one or more projects.

Command reference: aspire new

Example usage

The following example shows running the aspire new command to create a new Aspire project — select the play button to view terminal playback:

While command-line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience.

Initialize existing solutions

The aspire init command adds Aspire support to an existing .NET solution or creates a single-file AppHost. This is useful when you want to add Aspire orchestration capabilities to an existing application without creating an entirely new solution structure.

The command analyzes your existing solution and adds the necessary Aspire AppHost project or creates a minimal single-file AppHost, making it easy to adopt Aspire incrementally.

Command reference: aspire init

Start the Aspire AppHost

The aspire run command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the AppHost, launches the web dashboard, and prints a list of endpoints.

When aspire run starts, it searches the current directory for an AppHost project. If a project isn’t found, the subdirectories are searched until one is found. If no AppHost project is found, Aspire stops. Once a project is found, Aspire CLI takes the following steps:

1. Installs or verifies that Aspire’s local hosting certificates are installed and trusted.
2. Builds the AppHost project and its resources.
3. Starts the AppHost and its resources.
4. Starts the dashboard.

The following snippet is an example of the output displayed by the aspire run command:

Aspire CLI

Dashboard:  https://localhost:17244/login?t=9db79f2885dae24ee06c6ef10290b8b2

    Logs:  /home/vscode/.aspire/cli/logs/apphost-5932-2025-08-25-18-37-31.log

        Press CTRL+C to stop the apphost and exit.

Command reference: aspire run

Add integrations

The aspire add command is an easy way to add official integration packages to your AppHost project. Use this as an alternative to a NuGet search through your IDE. You can run aspire add <name|id> if you know the name or NuGet ID of the integration package. If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value.

Command reference: aspire add

Update Aspire packages

The aspire update command helps you keep your Aspire projects current by automatically detecting and updating outdated packages and templates. It finds outdated Aspire NuGet packages while respecting channel configurations and intelligently handles complex dependency graphs.

The command validates package compatibility before applying changes and provides detailed output showing which packages were updated.

Command reference: aspire update

Publish Aspire applications

The aspire publish command publishes resources by serializing them to disk. When this command is run, Aspire invokes registered PublishingCallbackAnnotation resource annotations, in the order they’re declared. These annotations serialize a resource so that it can be consumed by deployment tools.

Some integrations automatically register a PublishingCallbackAnnotation for you, for example:

• AzureEnvironmentResource generates Bicep assets
• DockerComposeEnvironmentResource generates docker-compose YAML
• KubernetesEnvironmentResource generates Kubernetes Helm charts

Command reference: aspire publish

Deploy Aspire solutions

The aspire deploy command is similar to aspire publish. After Aspire has invoked the publishing annotations to serialize resources to disk, it invokes DeployingCallbackAnnotation resource annotations, in the order they’re declared.

As of Aspire 9.4, Aspire doesn’t include any default deployment annotations for its resources, you must use the DeployingCallbackAnnotation to build your own.

Consejo

Consider this a good way to deploy your Aspire solution to a staging or testing environment.

Command reference: aspire deploy

Execute pipeline steps

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

Use this command to test individual pipeline stages during development or to execute only the dependencies needed for a particular step.

Command reference: aspire do

Run commands in resource context

The aspire exec command runs a command in the context of a specific Aspire resource, inheriting that resource’s configuration, including environment variables, connection strings, and working directory. This is particularly useful for scenarios like running Entity Framework migrations where you need to run commands with the same configuration as your application. For example, you can run aspire exec --resource api -- dotnet ef migrations add Init to run Entity Framework commands with the proper database connection strings automatically configured.

Command reference: aspire exec

Manage CLI configuration

The aspire config command lets you manage Aspire CLI configuration settings. Use it to list, get, set, or delete configuration values that control CLI behavior. This command is also used to toggle features on or off.

Command reference: aspire config

Manage CLI cache

The aspire cache command manages the disk cache used by the Aspire CLI. The CLI caches data such as downloaded templates, NuGet package information, and other temporary files to improve performance and reduce network requests.

Use aspire cache clear to remove all cached data. This is useful when troubleshooting CLI issues, freeing up disk space, or ensuring fresh data after updating the CLI.

Command reference: aspire cache