{"id":57845,"date":"2025-08-28T10:05:00","date_gmt":"2025-08-28T17:05:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=57845"},"modified":"2025-11-24T15:27:29","modified_gmt":"2025-11-24T23:27:29","slug":"getting-started-with-the-aspire-cli","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/getting-started-with-the-aspire-cli\/","title":{"rendered":"Getting Started with the Aspire CLI"},"content":{"rendered":"<p>The Aspire CLI is a powerful, cross-platform tool designed to streamline the development, management, and deployment of application systems. Whether you\u2019re 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.<\/p>\n<h2>1. Installing the Aspire CLI<\/h2>\n<p>Before you begin, make sure you have the <a href=\"https:\/\/dotnet.microsoft.com\/download\/dotnet\/9.0\">.NET 9.0 SDK<\/a> installed.<\/p>\n<p><strong>There are two main ways to install the Aspire CLI, with instructions for both Windows and Unix-based systems:<\/strong><\/p>\n<h3>a. As a Native Executable<\/h3>\n<h4>Windows<\/h4>\n<p>Open PowerShell and run:<\/p>\n<pre><code class=\"language-powershell\">Invoke-Expression \"&amp; { $(Invoke-RestMethod https:\/\/aspire.dev\/install.ps1) }\"<\/code><\/pre>\n<p>This installs Aspire CLI to <code>%USERPROFILE%\\.aspire\\bin<\/code> by default. You can customize the install path or version using script options (see the <a href=\"https:\/\/learn.microsoft.com\/dotnet\/aspire\/cli\/install?tabs=windows\">official docs<\/a> for details).<\/p>\n<h4>Unix (Linux\/macOS)<\/h4>\n<p>Open a terminal and run:<\/p>\n<pre><code class=\"language-bash\">curl -sSL https:\/\/aspire.dev\/install.sh | bash<\/code><\/pre>\n<p>This installs Aspire CLI to <code>$HOME\/.aspire\/bin<\/code> by default. You can customize the install path or version using script options (see the <a href=\"https:\/\/learn.microsoft.com\/dotnet\/aspire\/cli\/install?tabs=unix\">official docs<\/a> for details).<\/p>\n<h3>b. As a .NET Global Tool (Cross-platform)<\/h3>\n<p>Alternatively, you can install Aspire CLI as a global .NET tool (works on both Windows and Unix):<\/p>\n<pre><code class=\"language-bash\">dotnet tool install -g Aspire.Cli --prerelease<\/code><\/pre>\n<p><strong>Validate your installation:<\/strong><\/p>\n<pre><code class=\"language-bash\">aspire --version<\/code><\/pre>\n<p>If you see a version number, you\u2019re ready to go!<\/p>\n<hr \/>\n<h2>2. Creating a New Project with Templates<\/h2>\n<p>Aspire CLI makes it easy to start new projects using templates. Run:<\/p>\n<pre><code class=\"language-powershell\">aspire new<\/code><\/pre>\n<p>This command launches an interactive experience where you can select a template, name your project, and choose an output folder.<\/p>\n<p>The templates that are currently available with the CLI are:<\/p>\n<ul>\n<li><strong>Starter template<\/strong>: A collection of projects using .NET that demonstrate a simple system running with Aspire<\/li>\n<li><strong>AppHost and service defaults<\/strong>: Creates a solution with an AppHost project and a service defaults project, providing a ready-to-run distributed application setup.<\/li>\n<li><strong>AppHost<\/strong>: Generates just the AppHost project, which acts as the entry point and orchestrator for your distributed application.<\/li>\n<li><strong>Service defaults<\/strong>: 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.<\/li>\n<li><strong>Integration tests<\/strong>: Provides a template for writing integration tests with .NET, making it easier to test your distributed application&#8217;s components together.<\/li>\n<\/ul>\n<p>The CLI will download the latest templates and generate your project structure.<\/p>\n<p><div style=\"width: 640px;\" class=\"wp-video\"><video class=\"wp-video-shortcode\" id=\"video-57845-1\" width=\"640\" height=\"360\" preload=\"metadata\" controls=\"controls\"><source type=\"video\/webm\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-new.webm?_=1\" \/><a href=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-new.webm\">https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-new.webm<\/a><\/video><\/div><\/p>\n<hr \/>\n<h2>3. Adding Integrations and Packages<\/h2>\n<p>To add official integration packages (like databases, messaging, etc.) to your AppHost project, use:<\/p>\n<pre><code class=\"language-powershell\">aspire add<\/code><\/pre>\n<p>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.<\/p>\n<p><div style=\"width: 640px;\" class=\"wp-video\"><video class=\"wp-video-shortcode\" id=\"video-57845-2\" width=\"640\" height=\"360\" preload=\"metadata\" controls=\"controls\"><source type=\"video\/webm\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-add.webm?_=2\" \/><a href=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-add.webm\">https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-add.webm<\/a><\/video><\/div><\/p>\n<p>Here is a snapshot of what the integration package selection list looks like:<\/p>\n<pre><code class=\"language-bash\">\ud83d\udd0d  Finding app hosts...\ntestAspire\\testAspire.AppHost\\testAspire.AppHost.csproj\n\n\ud83d\uddc4  Created settings file at '.aspire\/settings.json'.\nSelect an integration to add:\n\n  azure-cosmosdb (Aspire.Hosting.Azure.CosmosDB)\n  azure-eventhubs (Aspire.Hosting.Azure.EventHubs)\n  azure-functions (Aspire.Hosting.Azure.Functions)\n  azure-keyvault (Aspire.Hosting.Azure.KeyVault)\n  azure-operationalinsights (Aspire.Hosting.Azure.OperationalInsights)\n&gt; azure-postgresql (Aspire.Hosting.Azure.PostgreSQL)\n  azure-redis (Aspire.Hosting.Azure.Redis)\n  azure-search (Aspire.Hosting.Azure.Search)\n  azure-servicebus (Aspire.Hosting.Azure.ServiceBus)\n  azure-signalr (Aspire.Hosting.Azure.SignalR)\n\n(Type to search)\n(Move up and down to reveal more choices)<\/code><\/pre>\n<hr \/>\n<h2>4. Running and Debugging Your Application<\/h2>\n<p>To start your application in development mode, use:<\/p>\n<pre><code class=\"language-powershell\">aspire run<\/code><\/pre>\n<p>This command:<\/p>\n<ul>\n<li>Configures the Aspire environment<\/li>\n<li>Builds and starts all resources defined by your AppHost<\/li>\n<li>Launches the Aspire dashboard for monitoring<\/li>\n<li>Prints a list of endpoints<\/li>\n<\/ul>\n<p><div style=\"width: 640px;\" class=\"wp-video\"><video class=\"wp-video-shortcode\" id=\"video-57845-3\" width=\"640\" height=\"360\" preload=\"metadata\" controls=\"controls\"><source type=\"video\/webm\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-run.webm?_=3\" \/><a href=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-run.webm\">https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2025\/08\/aspirecli-run.webm<\/a><\/video><\/div><\/p>\n<p>You\u2019ll see output like:<\/p>\n<pre><code class=\"language-bash\">Dashboard:  https:\/\/localhost:17178\/login?t=...\nLogs:  ...\/.aspire\/cli\/logs\/apphost-...log<\/code><\/pre>\n<p>The dashboard is your jumping off point, to see application logs, metrics, and even a network diagram of your system&#8217;s resources.<\/p>\n<p>Aspire logs are written to disk in case you need to examine how the Aspire processes are running.<\/p>\n<hr \/>\n<h2>5. Publishing Your Application<\/h2>\n<p>We&#8217;re working on the publishing feature, and some of what you will see is in preview mode.  When you\u2019re ready to publish, use:<\/p>\n<pre><code class=\"language-powershell\">aspire publish<\/code><\/pre>\n<p>This command serializes your resources for deployment tools. Depending on your integrations, it can generate assets for Azure, Docker Compose, or Kubernetes.<\/p>\n<p>There is also a <strong>deploy<\/strong> command available, but currently it does not have any functionality associated with it.<\/p>\n<hr \/>\n<h2>Conclusion &amp; Call to Action<\/h2>\n<p>The Aspire CLI is your gateway to building modern, distributed .NET applications with speed and confidence. From project creation to publishing, it\u2019s designed to make your workflow seamless and productive.<\/p>\n<p>As with all of .NET and Aspire, the source code is available on our <a href=\"https:\/\/github.com\/dotnet\/aspire\/tree\/main\/src\/Aspire.Cli\">GitHub repository<\/a><\/p>\n<p><strong>Ready to get started?<\/strong><br \/>\nInstall the Aspire CLI today and start building your next great application!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The Aspire CLI is here and you can use it to configure and run your applications<\/p>\n","protected":false},"author":405,"featured_media":58999,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685,7783,7689],"tags":[7768,7174],"class_list":["post-57845","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet","category-aspire","category-cloud-native","tag-aspire","tag-cli"],"acf":[],"blog_post_summary":"<p>The Aspire CLI is here and you can use it to configure and run your applications<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/57845","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/405"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=57845"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/57845\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/58999"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=57845"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=57845"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=57845"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}