Getting Started with the Aspire CLI

The Aspire CLI is a powerful, cross-platform tool designed to streamline the development, management, and deployment of application systems. Whether you’re building a simple website or an enterprise-scale distributed application with microservices and queues and databases, the Aspire CLI offers an interactive-first experience to help you create, run, and publish your projects with ease.

1. Installing the Aspire CLI

Before you begin, make sure you have the .NET 9.0 SDK installed.

There are two main ways to install the Aspire CLI, with instructions for both Windows and Unix-based systems:

a. As a Native Executable

Windows

Open PowerShell and run:

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

This installs Aspire CLI to %USERPROFILE%\.aspire\bin by default. You can customize the install path or version using script options (see the official docs for details).

Unix (Linux/macOS)

Open a terminal and run:

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

This installs Aspire CLI to $HOME/.aspire/bin by default. You can customize the install path or version using script options (see the official docs for details).

b. As a .NET Global Tool (Cross-platform)

Alternatively, you can install Aspire CLI as a global .NET tool (works on both Windows and Unix):

dotnet tool install -g Aspire.Cli --prerelease

Validate your installation:

aspire --version

If you see a version number, you’re ready to go!

2. Creating a New Project with Templates

Aspire CLI makes it easy to start new projects using templates. Run:

aspire new

This command launches an interactive experience where you can select a template, name your project, and choose an output folder.

The templates that are currently available with the CLI are:

Starter template: A collection of projects using .NET that demonstrate a simple system running with Aspire
AppHost and service defaults: Creates a solution with an AppHost project and a service defaults project, providing a ready-to-run distributed application setup.
AppHost: Generates just the AppHost project, which acts as the entry point and orchestrator for your distributed application.
Service defaults: Sets up a project with recommended defaults for building microservices and websites with .NET. This includes best practices for configuration and dependencies, and is intended to be included in other projects to enable those defaults.
Integration tests: Provides a template for writing integration tests with .NET, making it easier to test your distributed application’s components together.

The CLI will download the latest templates and generate your project structure.

3. Adding Integrations and Packages

To add official integration packages (like databases, messaging, etc.) to your AppHost project, use:

aspire add

You can specify a package name or NuGet ID as a command-line argument, or let the CLI present a list you can choose from with type-ahead searching. This simplifies adding dependencies without leaving your terminal.

Here is a snapshot of what the integration package selection list looks like:

🔍  Finding app hosts...
testAspire\testAspire.AppHost\testAspire.AppHost.csproj

🗄  Created settings file at '.aspire/settings.json'.
Select an integration to add:

  azure-cosmosdb (Aspire.Hosting.Azure.CosmosDB)
  azure-eventhubs (Aspire.Hosting.Azure.EventHubs)
  azure-functions (Aspire.Hosting.Azure.Functions)
  azure-keyvault (Aspire.Hosting.Azure.KeyVault)
  azure-operationalinsights (Aspire.Hosting.Azure.OperationalInsights)
> azure-postgresql (Aspire.Hosting.Azure.PostgreSQL)
  azure-redis (Aspire.Hosting.Azure.Redis)
  azure-search (Aspire.Hosting.Azure.Search)
  azure-servicebus (Aspire.Hosting.Azure.ServiceBus)
  azure-signalr (Aspire.Hosting.Azure.SignalR)

(Type to search)
(Move up and down to reveal more choices)

4. Running and Debugging Your Application

To start your application in development mode, use:

aspire run

This command:

Configures the Aspire environment
Builds and starts all resources defined by your AppHost
Launches the Aspire dashboard for monitoring
Prints a list of endpoints

You’ll see output like:

Dashboard:  https://localhost:17178/login?t=...
Logs:  .../.aspire/cli/logs/apphost-...log

The dashboard is your jumping off point, to see application logs, metrics, and even a network diagram of your system’s resources.

Aspire logs are written to disk in case you need to examine how the Aspire processes are running.

5. Publishing Your Application

We’re working on the publishing feature, and some of what you will see is in preview mode. When you’re ready to publish, use:

aspire publish

This command serializes your resources for deployment tools. Depending on your integrations, it can generate assets for Azure, Docker Compose, or Kubernetes.

There is also a deploy command available, but currently it does not have any functionality associated with it.

Conclusion & Call to Action

The Aspire CLI is your gateway to building modern, distributed .NET applications with speed and confidence. From project creation to publishing, it’s designed to make your workflow seamless and productive.

As with all of .NET and Aspire, the source code is available on our GitHub repository

Ready to get started? Install the Aspire CLI today and start building your next great application!