diff --git a/docs/cli-reference/aspire-add.md b/docs/cli-reference/aspire-add.md new file mode 100644 index 0000000000..28b2b1a142 --- /dev/null +++ b/docs/cli-reference/aspire-add.md @@ -0,0 +1,68 @@ +--- +title: aspire add command +description: Learn about the aspire add command and its usage. This command adds an integration package to an Aspire AppHost project. +ms.date: 07/11/2025 +--- +# aspire add command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire add` - Add an integration to the Aspire project. + +## Synopsis + +```dotnetcli +aspire add [] [options] +``` + +## Description + +The `aspire add` command searches NuGet for an integration package and adds it to the AppHost project. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +## Arguments + +The following arguments are available: + +- **`integration`** + + The name of the integration to add (for example: redis, postgres). + + If a partial name or invalid name is provided, the CLI searches NuGet for approximate matches and prints them in the terminal for the user to select. If no results are found, all packages are listed. + +## Options + +The following options are available: + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-v, --version`** + + The version of the integration to add. + +- **`-s, --source`** + + The NuGet source to use for the integration. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Finds an AppHost project and lists all Aspire integration packages from NuGet: + + ```Command + aspire add + ``` + +- Finds an AppHost project and adds the **kafka** (Aspire.Hosting.Kafka) integration package: + + ```Command + aspire add kafka --version 9.3.2 + ``` diff --git a/docs/cli-reference/aspire-config-delete.md b/docs/cli-reference/aspire-config-delete.md new file mode 100644 index 0000000000..c25b2e7a55 --- /dev/null +++ b/docs/cli-reference/aspire-config-delete.md @@ -0,0 +1,51 @@ +--- +title: aspire config delete command +description: Learn about the aspire config delete command and its usage. This command deletes an Aspire CLI config value by key name. +ms.date: 07/11/2025 +--- +# aspire config delete command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config delete` - Delete a configuration value. + +## Synopsis + +```dotnetcli +aspire config delete [options] +``` + +## Description + +The `aspire config delete` command delete's a config value by key name. + +[!INCLUDE [config-file-description](includes/config-file-description.md)] + +The command returns the following exit codes: + +- `0`—The command succeeded. +- `1`—The supplied key doesn't exist in the config file, or the config file is missing. + +## Arguments + +The following arguments are available: + +- **`key`** + + The configuration key to delete. + +## Options + +The following options are available: + +- **`-g, --global`** + + Delete the configuration value from the global `$HOME/.aspire/settings.json` instead of the local settings file. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config-get.md b/docs/cli-reference/aspire-config-get.md new file mode 100644 index 0000000000..d0406d39f2 --- /dev/null +++ b/docs/cli-reference/aspire-config-get.md @@ -0,0 +1,49 @@ +--- +title: aspire config get command +description: Learn about the aspire config get command and its usage. This command gets an Aspire CLI config value by key name. +ms.date: 07/11/2025 +--- +# aspire config get command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config get` - Get a configuration value. + +## Synopsis + +```dotnetcli +aspire config get [options] +``` + +## Description + +The `aspire config get` command retrieves a config value by key name. + +[!INCLUDE [config-file-description](includes/config-file-description.md)] + +If the config value doesn't exist in a local settings file, the config file is retrieved from the global settings file. + +The command returns the following exit codes: + +- `0`—The command succeeded. +- `10`—The supplied key doesn't exist in the config file, or the config file is missing. + +## Arguments + +The following arguments are available: + +- **`key`** + + The configuration key to retrieve. + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config-list.md b/docs/cli-reference/aspire-config-list.md new file mode 100644 index 0000000000..8af315a42a --- /dev/null +++ b/docs/cli-reference/aspire-config-list.md @@ -0,0 +1,36 @@ +--- +title: aspire config list command +description: Learn about the aspire config list command and its usage. This command lists all Aspire CLI config values. +ms.date: 07/11/2025 +--- +# aspire config list command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config list` - List all configuration values. + +## Synopsis + +```dotnetcli +aspire config list [options] +``` + +## Description + +The `aspire config list` command lists all config value by key name. + +[!INCLUDE [config-file-description](includes/config-file-description.md)] + +This command lists both the global and local settings. If a local setting overrides a global setting, only the local setting is displayed. + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config-set.md b/docs/cli-reference/aspire-config-set.md new file mode 100644 index 0000000000..3c66ce0d20 --- /dev/null +++ b/docs/cli-reference/aspire-config-set.md @@ -0,0 +1,50 @@ +--- +title: aspire config set command +description: Learn about the aspire config set command and its usage. This command sets an Aspire CLI config value by key name. +ms.date: 07/11/2025 +--- +# aspire config set command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config set` - Set a configuration value. + +## Synopsis + +```dotnetcli +aspire config set [options] +``` + +## Description + +The `aspire config set` command sets a config value by key name. + +[!INCLUDE [config-file-description](includes/config-file-description.md)] + +## Arguments + +The following arguments are available: + +- **`key`** + + The configuration key to set. + +- **`value`** + + The configuration value to set. + +## Options + +The following options are available: + +- **`-g, --global`** + + Set the configuration value globally in `$HOME/.aspire/settings.json` instead of the local settings file. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] diff --git a/docs/cli-reference/aspire-config.md b/docs/cli-reference/aspire-config.md new file mode 100644 index 0000000000..331c0efcf9 --- /dev/null +++ b/docs/cli-reference/aspire-config.md @@ -0,0 +1,45 @@ +--- +title: aspire config command +description: Learn about the aspire config command and its usage. This command driver is used to manage the Aspire CLI config settings. +ms.date: 07/11/2025 +--- +# aspire config command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions + +## Name + +`aspire config` - Manage configuration settings. + +## Synopsis + +```dotnetcli +aspire config [command] [options] +``` + +## Description + +The `aspire config` command driver provides commands to manage the Aspire CLI config settings. + +[!INCLUDE [config-file-description](includes/config-file-description.md)] + +## Options + +The following options are available: + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Commands + +The following commands are available: + +| Command | Status | Function | +|-----------------------------------------------------------|--------|--------------------------------| +| [`aspire config list`](aspire-config-list.md) | Stable | List all configuration values. | +| [`aspire config get `](aspire-config-get.md) | Stable | Get a configuration value. | +| [`aspire config set `](aspire-config-set.md) | Stable | Set a configuration value. | +| [`aspire config delete `](aspire-config-delete.md) | Stable | Delete a configuration value. | diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md new file mode 100644 index 0000000000..e9814386ad --- /dev/null +++ b/docs/cli-reference/aspire-deploy.md @@ -0,0 +1,76 @@ +--- +title: aspire deploy command +description: Learn about the aspire deploy command and its usage. This command first runs publishing mode, then invokes resource deployments declared by the app host. +ms.date: 07/11/2025 +--- +# aspire deploy command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. + +## Name + +`aspire deploy` - Deploy an Aspire app host project to its supported deployment targets. + +[!INCLUDE [mode-preview](includes/mode-preview.md)] + +## Synopsis + +```dotnetcli +aspire deploy [options] [[--] ...] +``` + +## Description + +The `aspire deploy` command is similar to [`aspire publish`](./aspire-publish.md). After Aspire has invoked the publishing annotations, it invokes `DeployingCallbackAnnotation` resource annotations, in the order they're declared. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +The command performs the following steps to run an AppHost project: + +- Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. +- Starts the app host in publish mode. +- Invokes all resource annotations. +- Invokes all `DeployingCallbackAnnotation` resource annotations. + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire publish from arguments for the app host. All arguments after this delimiter are passed to the app host. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-o, --output-path`** + + The output path for deployment artifacts. Defaults to a folder named _deploy_ in the current directory. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Search the current directory structure for AppHost projects to build, publish, and deploy: + + ```Command + aspire deploy + ``` + +- Publish and deploy a specific AppHost project: + + ```Command + aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' + ``` + +- Publish and deploy a specific AppHost project with arguments: + + ```Command + aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' -- -fast + ``` diff --git a/docs/cli-reference/aspire-exec.md b/docs/cli-reference/aspire-exec.md new file mode 100644 index 0000000000..336b261be9 --- /dev/null +++ b/docs/cli-reference/aspire-exec.md @@ -0,0 +1,58 @@ +--- +title: aspire exec command +description: Learn about the aspire exec command and its usage. This command builds and runs an Aspire AppHost project, then sends commands to a resource. +ms.date: 07/11/2025 +--- +# aspire exec command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. + +## Name + +`aspire exec` - Run an Aspire app host to execute a command against the resource. + +## Synopsis + +```dotnetcli +aspire exec [options] [[--] ...] +``` + +## Description + +The `aspire exec` command runs an AppHost project and runs a command in the context of one of the resources. + +You must specify either the `--resource` or the `--start-resource` option, and you must provide parameters with the `--` option. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire exec from arguments for the resource. All arguments after this delimiter are passed to the resource. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-r, --resource`** + + The name of the target resource to execute the command against. + +- **`-s, --start-resource`** + + The name of the target resource to start and execute the command against. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Builds and runs the AppHost project, then sends the command `migrate` to the `database1` resource: + + ```Command + aspire exec --resource database1 -- migrate + ``` diff --git a/docs/cli-reference/aspire-new.md b/docs/cli-reference/aspire-new.md new file mode 100644 index 0000000000..b2c99396b5 --- /dev/null +++ b/docs/cli-reference/aspire-new.md @@ -0,0 +1,78 @@ +--- +title: aspire new command +description: Learn about the aspire new command and its usage. This command creates new Aspire projects or solutions. +ms.date: 07/11/2025 +--- +# aspire new command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. + +## Name + +`aspire new` - Create a new Aspire project or solution. + +## Synopsis + +```dotnetcli +aspire new [command] [options] +``` + +## Description + +The `aspire new` command is the driver for creating Aspire projects, apps, or solutions, based on the Aspire templates. Each command specifies the template to use, and the options for the driver specify the options for the template. + +This command defaults to **interactive** mode. By issuing the command without any options, the command prompts you for the project template and version, name, and output folder. input to fill out the options. When the `--name`, `--output`, and `--version` options are provided, the command runs **non-interactive** and generates files based on the command template. + +## Options + +The following options are available: + +- **`-n, --name`** + + The name of the project to create. + +- **`-o, --output`** + + The output path for the project. + +- **`-s, --source`** + + The NuGet source to use for the project templates. + +- **`-v, --version`** + + The version of the project templates to use. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Commands + +Each command represents a template. Pass the `--help` parameter to the template command to print the options available to the template. + +| Command | Template | +|--------------------------|------------------------------| +| `aspire` | Aspire Empty App | +| `aspire-apphost` | Aspire App Host | +| `aspire-mstest` | Aspire Test Project (MSTest) | +| `aspire-nunit` | Aspire Test Project (NUnit) | +| `aspire-servicedefaults` | Aspire Service Defaults | +| `aspire-starter` | Aspire Starter App | +| `aspire-xunit` | Aspire Test Project (xUnit) | + +## Examples + +- Create an Aspire solution from the template. Because the template was selected (`aspire-starter`), you're prompted for the name, output folder, and template version. + + ```Command + aspire new aspire-starter + ``` + +- Create an AppHost project named `aspireapp` from the **9.3.1** templates and place the output in a folder named `aspire1`. + + ```Command + aspire new aspire-apphost --version 9.3.1 --name aspireapp1 --output ./aspire1 + ``` diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md new file mode 100644 index 0000000000..aaf4cc82f5 --- /dev/null +++ b/docs/cli-reference/aspire-publish.md @@ -0,0 +1,75 @@ +--- +title: aspire publish command +description: Learn about the aspire publish command and its usage. This command invokes resource publishers declared by the app host to serialize resources to disk. +ms.date: 07/11/2025 +--- +# aspire publish command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. + +## Name + +`aspire publish` - Generates deployment artifacts for an Aspire app host project. + +[!INCLUDE [mode-preview](includes/mode-preview.md)] + +## Synopsis + +```dotnetcli +aspire publish [options] [[--] ...] +``` + +## Description + +The `aspire publish` command publishes resources by serializing them to disk. When this command is run, Aspire invokes registered annotations for resources, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +The command performs the following steps to run an AppHost project: + +- Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. +- Starts the app host in publish mode. +- Invokes all annotations for resources. + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire publish from arguments for the AppHost. All arguments after this delimiter are passed to the AppHost. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-o, --output-path`** + + The output path for the generated artifacts. Defaults the current directory. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Search the current directory structure for AppHost projects to build and publish: + + ```Command + aspire publish + ``` + +- Publish a specific AppHost project: + + ```Command + aspire publish --project './projects/apphost/orchestration.AppHost.csproj' + ``` + +- Publish a specific AppHost project with arguments: + + ```Command + aspire publish --project './projects/apphost/orchestration.AppHost.csproj' -- -fast + ``` diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md new file mode 100644 index 0000000000..427219398f --- /dev/null +++ b/docs/cli-reference/aspire-run.md @@ -0,0 +1,85 @@ +--- +title: aspire run command +description: Learn about the aspire run command and its usage. This command runs an Aspire app host. +ms.date: 07/11/2025 +--- +# aspire run command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 and later versions. + +## Name + +`aspire run` - Run an Aspire app host in development mode. + +## Synopsis + +```dotnetcli +aspire run [options] [[--] ...] +``` + +## Description + +The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the app host, launches the web dashboard, and prints a list of endpoints. + +[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] + +The command performs the following steps to run an apphost project: + +- Creates or modifies the `.aspire/settings.json` config file in the current directory, and sets the `appHostPath` config value to the path of the AppHost project file. +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. +- Starts the dashboard. + +The following snippet is an example of the output displayed by the `aspire run` command: + +```Aspire CLI +Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 + + Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log + +Endpoints: webfrontend has endpoint https://localhost:7294 + webfrontend has endpoint http://localhost:5131 + apiservice has endpoint https://localhost:7531 + apiservice has endpoint http://localhost:5573 +``` + +## Options + +The following options are available: + +- **`--`** + + Delimits arguments to aspire run from arguments for the app host being run. All arguments after this delimiter are passed to the app host run. + +- [!INCLUDE [option-project](includes/option-project.md)] + +- **`-w, --watch`** + + Start project resources in watch mode. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Examples + +- Search the current directory structure for AppHost projects to build and run: + + ```Command + aspire run + ``` + +- Run a specific AppHost project: + + ```Command + aspire run --project './projects/apphost/orchestration.AppHost.csproj' + ``` + +- Run a specific AppHost project with arguments: + + ```Command + aspire run --project './projects/apphost/orchestration.AppHost.csproj' -- -fast + ``` diff --git a/docs/cli-reference/aspire.md b/docs/cli-reference/aspire.md new file mode 100644 index 0000000000..8ba9e7159c --- /dev/null +++ b/docs/cli-reference/aspire.md @@ -0,0 +1,70 @@ +--- +title: aspire command +description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage. +ms.date: 07/11/2025 +--- +# aspire command + +**This article applies to:** ✔️ Aspire CLI 9.4.0 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`. + +- [!INCLUDE [option-help](includes/option-help.md)] + +- [!INCLUDE [option-version](includes/option-version.md)] + +- [!INCLUDE [option-debug](includes/option-debug.md)] + +- [!INCLUDE [option-wait](includes/option-wait.md)] + +## Commands + +The following commands are available: + +| Command | Status | Function | +|--------------------------------------------------|---------|--------------------------------------------------------------------------| +| [`aspire add`](aspire-add.md) | Stable | Add an integration to the Aspire project. | +| [`aspire config`](aspire-configure.md) | Stable | Configures the Aspire environment. | +| [`aspire deploy`](aspire-deploy.md) | Preview | Deploys the artifacts created by `aspire publish`. | +| [`aspire exec`](aspire-exec.md) | Stable | Similar to the `aspire run` command, but passes commands to the apphost. | +| [`aspire new`](aspire-new.md) | Stable | Create an Aspire sample project from a template. | +| [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project. | +| [`aspire run`](aspire-run.md) | Stable | Run an Aspire apphost in development mode. | + + + +## Examples + +- Create an Aspire solution from the template: + + ```Command + aspire new aspire-starter + ``` + +- Run an Aspire AppHost project: + + ```Command + aspire run + ``` diff --git a/docs/cli-reference/includes/config-file-description.md b/docs/cli-reference/includes/config-file-description.md new file mode 100644 index 0000000000..6c140adc2f --- /dev/null +++ b/docs/cli-reference/includes/config-file-description.md @@ -0,0 +1,14 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- + +Aspire supports a local and global settings file. Settings defined in a local settings file override those set in the global settings file. + +- **Local settings** + + A local settings file is stored at `.aspire/settings.json` under the current directory. + +- **Global settings** + + The global settings file is stored at `$HOME/.aspire/settings.json`. diff --git a/docs/cli-reference/includes/mode-preview.md b/docs/cli-reference/includes/mode-preview.md new file mode 100644 index 0000000000..d220c730c7 --- /dev/null +++ b/docs/cli-reference/includes/mode-preview.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- + +> [!IMPORTANT] +> This command is in preview and subject to change. diff --git a/docs/cli-reference/includes/option-debug.md b/docs/cli-reference/includes/option-debug.md new file mode 100644 index 0000000000..da55b77ef0 --- /dev/null +++ b/docs/cli-reference/includes/option-debug.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- +**`-d, --debug`** + + Enable debug logging to the console, which prints detailed information about what .NET Aspire CLI is doing when a command is run. diff --git a/docs/cli-reference/includes/option-help.md b/docs/cli-reference/includes/option-help.md new file mode 100644 index 0000000000..43cb668cda --- /dev/null +++ b/docs/cli-reference/includes/option-help.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- +**`-?, -h, --help`** + + Prints help and usage documentation for the available commands and options. diff --git a/docs/cli-reference/includes/option-project.md b/docs/cli-reference/includes/option-project.md new file mode 100644 index 0000000000..a078225fea --- /dev/null +++ b/docs/cli-reference/includes/option-project.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- +**`--project`** + + The path to the Aspire AppHost project file. diff --git a/docs/cli-reference/includes/option-version.md b/docs/cli-reference/includes/option-version.md new file mode 100644 index 0000000000..6db6a6547f --- /dev/null +++ b/docs/cli-reference/includes/option-version.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- +**`--version`** + + Prints the version of the Aspire CLI tool. diff --git a/docs/cli-reference/includes/option-wait.md b/docs/cli-reference/includes/option-wait.md new file mode 100644 index 0000000000..2e8097aaf5 --- /dev/null +++ b/docs/cli-reference/includes/option-wait.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- +**`--wait-for-debugger`** + + Wait for a debugger to attach before running a command. diff --git a/docs/cli-reference/includes/project-search-logic-description.md b/docs/cli-reference/includes/project-search-logic-description.md new file mode 100644 index 0000000000..1a1c49d51a --- /dev/null +++ b/docs/cli-reference/includes/project-search-logic-description.md @@ -0,0 +1,20 @@ +--- +ms.date: 07/11/2025 +ms.topic: include +--- + +The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: + +- The `--project` option. + + This option specifies the path to a project to process. + +- The `.aspire/settings.json` config file. + + If the config file path exists in the current directory, it's used. If not, the CLI walks up the directory structure looking for the config file. If it finds a config file, it reads the `appHostPath` setting value as the project to process. + +- Searches the current directory and subdirectories. + + Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it's automatically selected. If multiple projects are discovered, they're printed to the terminal for the user to manually select one of the projects. + + Once a project selected, either automatically or manually, the path to the project is stored in the `.aspire/settings.json` config 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..cae03ae01f --- /dev/null +++ b/docs/cli/overview.md @@ -0,0 +1,95 @@ +--- +title: .NET Aspire CLI Overview and Commands +description: Learn about the 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 +--- + +# Aspire CLI Overview + +The Aspire CLI (`aspire` command) is a cross-platform tool that provides command-line functionality to create, manage, run, and publish polyglot Aspire projects. Use the Aspire CLI to streamline development workflows and coordinate services for distributed applications. + +The Aspire CLI is an interactive-first experience. + +- [Install .NET Aspire CLI.](install.md) +- [`aspire` command reference.](../cli-reference/aspire.md) + +## Use templates + +[_Command reference: `aspire new`_](../cli-reference/aspire-new.md) + +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. + +## Start the app host + +[_Command reference: `aspire run`_](../cli-reference/aspire-run.md) + +The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the app host, launches the web dashboard, and prints a list of endpoints. + +When `aspire run` starts, it searches the current directory for an AppHost project. If a project isn't found, the sub directories are searched until one is found. If no AppHost project is found, Aspire stops. Once a project is found, Aspire CLI takes the following steps: + +- Installs or verifies that Aspire's local hosting certificates are installed and trusted. +- Builds the AppHost project. +- Starts the app host and its resources. +- Starts the dashboard. + +The following snippet is an example of the output displayed by the `aspire run` command: + +```Aspire CLI +Dashboard: https://localhost:17178/login?t=17f974bf68e390b0d4548af8d7e38b65 + + Logs: /home/vscode/.aspire/cli/logs/apphost-1295-2025-07-14-18-16-13.log + +Endpoints: webfrontend has endpoint https://localhost:7294 + webfrontend has endpoint http://localhost:5131 + apiservice has endpoint https://localhost:7531 + apiservice has endpoint http://localhost:5573 +``` + +## Add integrations + +[_Command reference: `aspire add`_](../cli-reference/aspire-add.md) + +The `aspire add` command is an easy way to add official integration packages to your AppHost project. 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 (preview) + +[_Command reference: `aspire publish`_](../cli-reference/aspire-publish.md) + +The `aspire publish` command publishes resources by serializing them to disk. When this command is run, Aspire invokes registered resource annotations, in the order they're declared. These annotations serialize a resource so that it can be consumed by deployment tools. + +Some integrations automatically register a `PublishingCallbackAnnotation` for you, for example: + +- generates Bicep assets. +- generates docker-compose yaml. +- generates Kubernetes Helm charts. + +## Deploy Aspire applications (preview) + +[_Command reference: `aspire deploy`_](../cli-reference/aspire-deploy.md) + +The `aspire deploy` command is similar to `aspire publish`. After Aspire has invoked the publishing annotations to serialize resources to disk, it invokes `DeployingCallbackAnnotation` resource annotations, in the order they're declared. + +As of Aspire 9.4, Aspire doesn't include any default deployment annotations for its resources, you must use the `DeployingCallbackAnnotation` to build your own. + +> [!TIP] +> Consider this a good way to deploy your Aspire solution to a staging or testing environment. + +## Run commands in resource context (preview) + +[_Command reference: `aspire exec`_](../cli-reference/aspire-exec.md) + +The `aspire exec` command runs a command in the context of a specific Aspire resource, inheriting that resource's configuration, including environment variables, connection strings, and working directory. This is particularly useful for scenarios like running Entity Framework migrations where you need to run commands with the same configuration as your application. For example, you can run `aspire exec --resource api -- dotnet ef migrations add Init` to run Entity Framework commands with the proper database connection strings automatically configured. diff --git a/docs/fundamentals/setup-tooling.md b/docs/fundamentals/setup-tooling.md index a4fb2e10ef..0257cf09af 100644 --- a/docs/fundamentals/setup-tooling.md +++ b/docs/fundamentals/setup-tooling.md @@ -258,6 +258,24 @@ Once you create a new .NET Aspire project, you run and debug the app, stepping t :::zone-end +## 🖥️ Aspire CLI + +🧪 The Aspire CLI is **still in preview** and under active development. Expect more features and polish in future releases. + +📦 To install: + +On Windows: + +```powershell +iex "& { $(irm https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.ps1) }" +``` + +On Linux, or macOS: + +```sh +curl -sSL https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.sh | bash +``` + ## See also - [Unable to install .NET Aspire workload](../troubleshooting/unable-to-install-workload.md) diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md index 48a29a2a04..26d30e9720 100644 --- a/docs/get-started/build-your-first-aspire-app.md +++ b/docs/get-started/build-your-first-aspire-app.md @@ -221,6 +221,24 @@ The preceding code: For more information, see [Make HTTP requests with the `HttpClient`](/dotnet/fundamentals/networking/http/httpclient) class. +## 🖥️ Aspire CLI + +🧪 The Aspire CLI is **still in preview** and under active development. Expect more features and polish in future releases. + +📦 To install: + +On Windows: + +```powershell +iex "& { $(irm https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.ps1) }" +``` + +On Linux, or macOS: + +```sh +curl -sSL https://github.com/dotnet/aspire/raw/refs/heads/main/eng/scripts/get-aspire-cli.sh | bash +``` + ## See also - [.NET Aspire integrations overview](../fundamentals/integrations-overview.md) diff --git a/docs/toc.yml b/docs/toc.yml index 240401642e..7874a2756e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -101,6 +101,42 @@ 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: aspire add + href: cli-reference/aspire-add.md + - name: aspire deploy + href: cli-reference/aspire-deploy.md + - name: aspire config + items: + - name: aspire config [command] + href: cli-reference/aspire-config.md + - name: aspire config list + href: cli-reference/aspire-config-list.md + - name: aspire config get + href: cli-reference/aspire-config-get.md + - name: aspire config set + href: cli-reference/aspire-config-set.md + - name: aspire config delete + href: cli-reference/aspire-config-delete.md + - name: aspire exec + href: cli-reference/aspire-exec.md + - name: aspire new + href: cli-reference/aspire-new.md + - name: aspire publish + href: cli-reference/aspire-publish.md + - name: aspire run + href: cli-reference/aspire-run.md + - name: Testing items: - name: Overview