diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md new file mode 100644 index 0000000000..705139cb45 --- /dev/null +++ b/docs/cli-reference/aspire.md @@ -0,0 +1,75 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 06/26/2025 +--- +# dotnet command + +**This article applies to:** ✔️ Aspire CLI 9.3.1 and later versions + +## Name + +`aspire` - The generic driver for the Aspire CLI. + +## Synopsis + +To get information about the available commands and the environment: + +```dotnetcli +aspire [command] [options] +``` + +## Description + +The `aspire` command provides commands for working with Aspire projects. For example `aspire run` runs an Aspire AppHost project. + +## Options + +The following options are available when `aspire` is used by itself, without specifying a command. For example, `aspire --version`. + +- **`-?, -h, --help`** + + Prints out help and usage documentation for the available commands and options. + +- **`--version`** + + Prints the version of the .NET Aspire CLI tool. + +- **`-d, --debug`** + + Enable debug logging to the console, which prints out detailed information about what .NET Aspire CLI is doing when a command is run. + +- **`--wait-for-debugger`** + + Wait for a debugger to attach before running a command. + +## Commands + +| Command | Function | +|-------------------------------------|----------------------------------------------------------------| +| [aspire new](aspire-new.md) | Create an Aspire sample project or solution from a template. | +| [aspire run](aspire-run.md) | Run an Aspire app host in development mode. | +| [aspire add](aspire-add.md) | Add an integration to the Aspire project. | +| [aspire publish](aspire-publish.md) | Generates deployment artifacts for an Aspire app host project. | +| [aspire config](aspire-config.md) | | +| [aspire exec](aspire-exec.md) | | + +## Examples + +Create an Aspire solution from the template: + +```dotnetcli +aspire new aspire-starter +``` + +Run an Aspire app host project: + +```command +aspire run +``` + +## See also + +- [Environment variables used by .NET SDK, .NET CLI, and .NET runtime](dotnet-environment-variables.md) +- [Runtime Configuration Files](https://github.com/dotnet/sdk/blob/main/documentation/specs/runtime-configuration-file.md) +- [.NET runtime configuration settings](../runtime-config/index.md) \ No newline at end of file diff --git a/docs/cli/install.md b/docs/cli/install.md new file mode 100644 index 0000000000..d8de103752 --- /dev/null +++ b/docs/cli/install.md @@ -0,0 +1,44 @@ +--- +title: Install .NET Aspire CLI +description: Learn how to install .NET Aspire CLI, which is a .NET global tool. Use the .NET Aspire CLI to create, run, and manage .NET Aspire projects. +author: adegeo +ms.author: adegeo +ms.topic: install-set-up-deploy +ms.date: 06/26/2025 + +#customer intent: As a developer, I want to install the .NET Aspire CLI so that I can create, run, and manage .NET Aspire projects. + +--- + +# Install .NET Aspire CLI + +This article teaches you how to install .NET Aspire CLI, which is a .NET global tool used to manage your .NET Aspire projects. + +## Prerequisites + +- [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET SDK 9.0](https://dotnet.microsoft.com/download/dotnet/9.0). + +## Install the global tool + +Use the `dotnet tool` command to install .NET Aspire CLI global tool. The name of the global tool is [Aspire.Cli](https://www.nuget.org/packages/Aspire.CLI). + +01. Open a terminal. +01. Run the following command to install Aspire CLI: + + ```dotnetcli + dotnet tool install -g Aspire.Cli --prerelease + ``` + +## Validation + +To validate that the global tool is installed, use the `--version` option to query Aspire CLI for a version number: + +``` +aspire --version +``` + +If that command works, you're presented with the version of the .NET Aspire CLI tool: + +``` +9.3.1-preview.1.25305.6+5bc26c78ff8c7be825d0ae33633a1ae9f1d64a67 +``` diff --git a/docs/cli/overview.md b/docs/cli/overview.md new file mode 100644 index 0000000000..d17cad2c4f --- /dev/null +++ b/docs/cli/overview.md @@ -0,0 +1,76 @@ +--- +title: .NET Aspire CLI Overview and Commands +description: Learn .NET Aspire CLI commands for creating projects, running an app host, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. +ms.date: 06/26/2025 +ms.topic: overview +ms.custom: + - ai-gen-docs-bap + - ai-gen-title + - ai-seo-date:06/26/2025 + - ai-gen-description +--- + +# .NET Aspire CLI Overview + +// TODO: More selling of why you want to use this instead of the .NET CLI you're probably already familiar with. + +The .NET Aspire CLI (`aspire` command) is a .NET global tool that provides command-line functionality to create, manage, run, and publish Aspire projects. Use the .NET Aspire CLI to streamline development workflows for distributed applications. + +The Aspire CLI is an interactive-first experience. + +- [Install .NET Aspire CLI](install.md) + +## Create projects + +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, Azure 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. + +While command line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience. + +## Run the app host project + +The `aspire run` command runs the app host project in development mode, which configures the Aspire environment, builds the app host, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the app host project in your IDE of choice, however, a terminal dashboard is also visible. + +When `aspire run` starts, it searches the current directory for an app host. If an app host isn't found, the sub directories are searched until an app host is found. If no app host is found, Aspire stops. Once an app host is found, Aspire CLI takes the following stesp: + +- Installs or verifies that Aspires local hosting certificates are installed and trusted. +- Builds the app host project. +- Starts the app host. +- Starts the dashboard. +- Displays a terminal-based dashboard. + + + +The following snippet is an example of the terminal dashboard: + +```Aspire CLI +Dashboard: +📈 Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0a + +╭─────────────┬─────────┬─────────┬────────────────────────╮ +│ Resource │ Type │ State │ Endpoint(s) │ +├─────────────┼─────────┼─────────┼────────────────────────┤ +│ apiservice │ Project │ Running │ https://localhost:7422 │ +│ │ │ │ http://localhost:5327 │ +│ webfrontend │ Project │ Running │ https://localhost:7241 │ +│ │ │ │ http://localhost:5185 │ +╰─────────────┴─────────┴─────────┴────────────────────────╯ +Press CTRL-C to stop the app host and exit. +``` + +## Add integrations + +The `aspire add` command is an easy way to add official integration packages to your app host. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` 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. + + + +## Publish Aspire applications + +// TODO: Stuff about publishing + +## Configure Aspire environment + + diff --git a/docs/toc.yml b/docs/toc.yml index 240401642e..2d89d73851 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -101,6 +101,18 @@ items: - name: Microsoft-collected dashboard telemetry href: fundamentals/dashboard/microsoft-collected-dashboard-telemetry.md +- name: Aspire CLI + displayName: aspire cli,aspire command line interface,aspire commands,cli + items: + - name: Overview + href: cli/overview.md + - name: Install + href: cli/install.md + - name: aspire command reference + items: + - name: aspire + href: cli-reference/aspire.md + - name: Testing items: - name: Overview