Mastering the Official .NET Aspire CLI: From Dev to Deployment

In our previous deep dives, we explored the inner workings of .NET Aspire—from its zero-config C# orchestration model to its powerful OpenTelemetry observability engine.

While many developers are familiar with running and managing Aspire solutions via IDEs like Visual Studio or JetBrains Rider, the .NET team has introduced a first-class, cross-platform command-line companion: the official .NET Aspire CLI (aspire).

If you want to build robust, automation-friendly CI/CD pipelines, or if you simply prefer the speed and control of a terminal-first workflow, mastering this tool is essential.

In this guide, we will explore how to install, navigate, and utilize the official Aspire CLI from development all the way to cloud deployment, as documented on the official aspire.dev portal.

What is the .NET Aspire CLI?

The Aspire CLI (aspire) is a unified, cross-platform command-line tool designed to streamline managing the lifecycle of your distributed .NET applications.

Rather than relying on the general dotnet CLI or IDE features, aspire provides dedicated commands for the specific workflows required by distributed orchestration:

Interactive Scaffolding: Starting new projects or adding Aspire to legacy apps.
Package Management: Instantly finding and adding Aspire hosting integrations.
Local Orchestration: Running your entire multi-project application with a single command.
Deployment Publishing: Generating platform-neutral execution and container artifacts ready for production.

Installing the Aspire CLI

The Aspire CLI is packaged as a standard global .NET tool, making it easy to install on Windows, macOS, or Linux. Run the following command in your terminal:

dotnet tool install --global Aspire.Cli

[!NOTE] Ensure you have the required .NET SDK version matching your Aspire workload (e.g., .NET 8 or newer).

To verify that the installation succeeded and inspect the available commands, run:

aspire --help

1. Scaffolding and Managing Integrations

The Aspire CLI makes bootstrapping and maintaining your application’s architecture incredibly straightforward.

Scaffold a New Project

To start a new .NET Aspire application from scratch, you don’t need an IDE. Run:

aspire new

This launches an interactive, terminal-based wizard that lets you choose starter templates (such as the standard .NET Aspire Starter Application), name your solution, and define the output folders.

Add Aspire to an Existing Application

If you already have a repository with microservices or APIs and want to bring them under .NET Aspire’s orchestrator, run:

aspire init

This command analyzes your current directory structure, detects projects, and automatically scaffolds the C# AppHost and ServiceDefaults projects.

Add Hosting Integrations

To connect databases, caches, or message queues to your orchestrator, you can search and add packages natively using aspire add:

aspire add aspire-hosting-redis

The tool searches NuGet, downloads the package, and references it in your AppHost project, saving you from manual XML package reference edits.

2. Orchestrating in Development

To start your entire distributed application locally—along with its containers, databases, and dependencies—simply run:

aspire run

When you execute aspire run, the CLI performs several operations:

Evaluates the AppHost: Compiles and starts the C# orchestration project.
Launches Containers: Spins up any required Redis, Postgres, or RabbitMQ containers defined in your C# code.
Bootstraps Observability: Launches the Aspire Dashboard locally and prints its URL.
Injects Endpoints: Dynamically maps connection strings and environment variables across your services.

You can inspect structured logs, distributed traces, and live metrics in your terminal or via the web dashboard.

3. The Deployment Story: Publish and Deploy

Taking a distributed application from localhost to a production cloud environment requires converting the C# resource definitions into platform-native code (like Docker Compose YAML, Kubernetes manifests, or Azure Bicep).

The Aspire CLI handles this transition using two powerful commands:

graph LR
    AppHost[C# AppHost] -->|aspire publish| Artifacts[Deployment Artifacts]
    Artifacts -->|aspire deploy| Cloud[Target Cloud Environment]

Step A: Publishing Artifacts

The first phase of the deployment pipeline is packaging. The publish command serializes the resources declared in your AppHost into intermediate, parameterized deployment assets:

aspire publish --output-path ./aspire-output

What it generates: Depending on the integrations and compute platforms you are targeting, aspire publish compiles Docker Compose configurations, Kubernetes manifests, or cloud-specific templates (like Azure Bicep files).
Platform Neutrality: By exporting these parameterized templates to an output directory (defaulting to ./aspire-output), it allows developers to audit, customize, and version-control their production assets before pushing them to the cloud.

Step B: Deploying

Once the deployment assets are built and parameterized, you can execute the second command:

aspire deploy --output-path ./aspire-output

This command takes the generated templates, prompts for or resolves environment variables and secret parameters, and deploys the entire topology directly to your active target environment.

Comparing the Deployment Toolchain

As a Cloud Architect, it is crucial to understand how the official Aspire CLI fits alongside other ecosystem deployment tools:

CLI Tool	Target Focus	Best Used For
Aspire CLI (`aspire`)	Platform-Neutral	Local development, scaffolding, and exporting standard deployment manifests (YAML, Compose, Bicep) for CI/CD.
Azure Developer CLI (`azd`)	Azure Container Apps / ACA	Optimized, end-to-end cloud deployment directly to Azure. Highly recommended for seamless Azure PaaS targets (`azd up`).
Aspirate CLI (`aspirate`)	Kubernetes (AKS/EKS/GKE)	Community-driven CLI specialized in converting Aspire manifests into highly custom Helm charts or Kustomize files.

Command Reference Cheat Sheet

Here is a summary of the most useful commands exposed by the official Aspire CLI:

Command	Description
`aspire new`	Interactively scaffolds a new .NET Aspire project from templates.
`aspire init`	Adds Aspire orchestration to an existing repository.
`aspire add`	Adds official hosting integrations to your `AppHost` project.
`aspire run`	Starts the orchestrator, container dependencies, and the dashboard.
`aspire publish`	Generates parameterized intermediate deployment artifacts.
`aspire deploy`	Deploys published artifacts directly to the target environment.
`aspire exec`	Runs a command with connection strings and environment variables injected.
`aspire do`	Executes fine-grained build or pipeline steps defined in the AppHost.

Conclusion

The official .NET Aspire CLI (aspire) is a game-changer for terminal-first development and DevOps automation. By separating development (aspire run), artifact generation (aspire publish), and execution (aspire deploy), Microsoft has created a flexible, platform-neutral toolchain that integrates seamlessly into any cloud-native pipeline.

Whether you are targeting container environments on-premise, deploying to Kubernetes clusters, or shipping to serverless Azure PaaS, the Aspire CLI provides the control, predictability, and automation power necessary for enterprise systems.

Have you integrated the official Aspire CLI into your CI/CD pipelines? What has been your experience using aspire publish vs standard Docker tools? Let’s discuss in the comments below!