The Aspire CLI

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

The Aspire CLI is designed to complement the .NET SDK and provides an interactive-first experience for working with Aspire projects directly from the command line.

Why Use the Aspire CLI?

While you can use the dotnet CLI with Aspire templates, the Aspire CLI offers several advantages:

• Interactive Project Creation: aspire new provides an interactive experience for creating Aspire projects
• Simplified Execution: aspire run automatically builds and runs your AppHost with the dashboard
• Easy Integration Management: aspire add makes it simple to add official integration packages
• Deployment Support: Deploy your applications with aspire deploy
• Configuration Management: Manage CLI settings with aspire config

Installation

There are two ways to install the Aspire CLI:

Option 1: Install Script (Recommended)

Install as a native executable using the install script:

Windows (PowerShell):

Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) }"

Linux/macOS (bash):

curl -sSL https://aspire.dev/install.sh | bash

This installs the Aspire CLI to:

• Windows: %USERPROFILE%\.aspire\bin
• Linux/macOS: $HOME/.aspire/bin

The installer automatically adds this location to your PATH.

Option 2: .NET Global Tool

Install as a .NET global tool:

dotnet tool install -g Aspire.Cli

To update an existing installation:

dotnet tool update -g Aspire.Cli

Verify Installation

To verify the installation and check the version:

aspire --version

Core Commands

aspire new

Creates one or more Aspire projects using an interactive experience.

aspire new

This command guides you through:

1. Selecting a project template
2. Naming your project
3. Choosing the output folder
4. Downloading the latest templates and generating the project(s)

You can also specify options directly:

aspire new --template starter-app --name MyAspireApp

aspire run

Runs the AppHost project in development mode.

aspire run

What this command does:

• Configures the Aspire environment
• Builds the AppHost project and its resources
• Starts the AppHost and all defined resources
• Launches the Aspire Dashboard
• Prints a list of endpoints

You can specify the AppHost project path:

aspire run --project ./src/MyApp.AppHost

aspire add

Adds official Aspire integration packages to your AppHost project.

aspire add

This provides an interactive list of available integrations like:

• PostgreSQL
• Redis
• RabbitMQ
• Azure Cosmos DB
• Azure Storage
• And many more

You can also specify the integration directly:

aspire add postgres
aspire add redis
aspire add rabbitmq

aspire deploy

Deploys your application by resolving parameters and applying changes to a target environment.

aspire deploy

This command extends the capabilities of aspire publish to actively deploy to a target environment like Azure Container Apps or Kubernetes.

aspire publish

Publishes resources by serializing them to a manifest file.

aspire publish

This generates a deployment manifest that describes your application's resources and dependencies.

aspire config

Manages Aspire CLI configuration settings.

# List all configuration values
aspire config list

# Get a specific configuration value
aspire config get <key>

# Set a configuration value
aspire config set <key> <value>

# Delete a configuration value
aspire config delete <key>

aspire exec

Runs a command in the context of a specific Aspire resource.

aspire exec <resource-name> -- <command>

For example, to execute a command inside a container resource:

aspire exec my-api -- dotnet --version

Common Workflows

Creating a New Aspire Project

# Interactive mode
aspire new

# Or specify options directly
aspire new --template starter-app --name MyDistributedApp
cd MyDistributedApp

Running Your Application

# From the solution directory
aspire run

# Or specify the AppHost project
aspire run --project ./src/MyApp.AppHost

Adding Integrations

# Navigate to your AppHost project directory
cd src/MyApp.AppHost

# Add integrations interactively
aspire add

# Or add specific integrations
aspire add postgres
aspire add redis

Deploying to Azure

# First, publish the manifest
aspire publish

# Then deploy
aspire deploy

Aspire CLI vs. dotnet CLI

While both can work with Aspire projects, here's when to use each:

Task	Use Aspire CLI	Use dotnet CLI
Create new Aspire projects	aspire new (interactive)	dotnet new aspire
Run AppHost with dashboard	aspire run (simplified)	dotnet run --project AppHost
Add integrations	aspire add (easy)	dotnet add package (manual)
Build solutions	-	dotnet build
Run tests	-	dotnet test
Deploy applications	aspire deploy	-

The Aspire CLI is designed to enhance (not replace) the dotnet CLI, providing a better experience for Aspire-specific workflows.

Next Steps

Now that you understand the Aspire CLI, you can use it alongside the traditional dotnet CLI for a more streamlined development experience. In the next sections, we'll run our Aspire application and explore the Dashboard.