From d1ff29dbcbc4aaf0e16d5addba0c4fec4d918e88 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 29 Aug 2025 11:59:24 -0700 Subject: [PATCH 1/6] Add install script reference --- docs/cli/install-script-reference.md | 166 +++++++++++++++++++++++++++ docs/cli/install.md | 32 +++++- docs/toc.yml | 2 + 3 files changed, 198 insertions(+), 2 deletions(-) create mode 100644 docs/cli/install-script-reference.md diff --git a/docs/cli/install-script-reference.md b/docs/cli/install-script-reference.md new file mode 100644 index 0000000000..670d7d23b4 --- /dev/null +++ b/docs/cli/install-script-reference.md @@ -0,0 +1,166 @@ +--- +title: Install .NET Aspire CLI +description: Learn about the aspire-install scripts to install the .NET Aspire CLI. Use the .NET Aspire CLI to create, run, and manage .NET Aspire projects. +author: adegeo +ms.author: adegeo +ms.date: 08/28/2025 +ai-usage: ai-assisted +#customer intent: As a developer, I need the aspire-install script reference so that I know what options it provides when installing the Aspire CLI. +--- + +# aspire-install script reference + +This article contains the syntax of the aspire install PowerShell and Bash scripts. To download the script, see [Install as a native executable](install.md#install-as-a-native-executable). + +## Name + +`aspire-install.ps1` | `aspire-install.sh` - Scripts used to install the Aspire CLI. + +## Synopsis + +Windows: + +```powershell +aspire-install.ps1 [-InstallPath ] [-Version ] [-Quality ] + [-OS ] [-Architecture ] [-KeepArchive] [-Help]" +``` + +Linux/macOS: + +```bash +aspire-install.sh [--install-path ] [--version ] [--quality ] + [--os ] [--arch ] [--keep-archive] [--verbose] [--help] +``` + +## Description + +The `aspire-install` scripts perform a nonadmin installation of the Aspire CLI. + +> [!IMPORTANT] +> The Aspire CLI is **still in preview** and under active development. + +### Script behavior + +Both scripts behave the same way. They download the Aspire CLI for the target platform, install it to the specified location, and add it to your PATH environment variable. + +By default, the installation scripts download and install the latest stable release of the Aspire CLI. Specify a different version with the `-Version|--version` argument or a different quality level with the `-Quality|--quality` argument. + +Unless changed with the `-InstallPath|--install-path` argument, the script installs to a user-specific location: `%USERPROFILE%\.aspire\bin` on Windows or `$HOME/.aspire/bin` on Linux/macOS. + +## Options + +- **`-InstallPath|--install-path `** + + Specifies the installation path. The directory is created if it doesn't exist. The default value is *%USERPROFILE%\.aspire\bin* on Windows and *$HOME/.aspire/bin* on Linux/macOS. The Aspire CLI executable is placed directly in this directory. + +- **`-Version|--version `** + + Represents a specific version to install. For example: `9.4`. If not specified, the latest stable version is installed. + +- **`-Quality|--quality `** + + Downloads the specified quality build. The possible values are: + + - `release`: The latest stable release (default). + - `staging`: Builds from the current release branch (prerelease builds). + - `dev`: Latest builds from the `main` branch (development builds). + + The different quality values signal different stages of the release process: + + - `release`: The final stable releases of the Aspire CLI. Intended for production use. + - `staging`: Prerelease builds intended for testing upcoming releases. Not recommended for production use. + - `dev`: The latest builds from the main development branch. They're built frequently and aren't fully tested. Not recommended for production use but can be used to test specific features or fixes immediately after they're merged. + +- **`-OS|--os `** + + Specifies the operating system for which the CLI is being installed. Possible values are: `win`, `linux`, `linux-musl`, `osx`. + + The parameter is optional and should only be used when it's required to override the operating system that is detected by the script. + +- **`-Architecture|--arch `** + + Architecture of the Aspire CLI binaries to install. Possible values are `x64`, `x86`, `arm64`. The default behavior is to autodetect the current system architecture. + +- **`-KeepArchive|--keep-archive`** + + If you set this option, the script keeps the downloaded archive files and temporary directory after installation. By default, the script deletes the archive after extraction and cleans up the temporary directory. + +- **`--verbose`** + + Displays diagnostics information. (Linux/macOS only) + +- **`-Help|--help`** + + Prints help information for the script. + +## Examples + +- Install the latest stable version to the default location: + + Windows: + + ```powershell + Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) }" + ``` + + macOS/Linux: + + ```bash + curl -sSL https://aspire.dev/install.sh | bash + ``` + +- Install to a custom directory: + + Windows: + + ```powershell + Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -InstallPath 'C:\Tools\Aspire'" + ``` + + macOS/Linux: + + ```bash + curl -sSL https://aspire.dev/install.sh | bash -s -- --install-path "/usr/local/bin" + ``` + +- Install a specific version: + + Windows: + + ```powershell + Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -Version '9.4'" + ``` + + macOS/Linux: + + ```bash + curl -sSL https://aspire.dev/install.sh | bash -s -- --version "9.4" + ``` + +- Install development builds: + + Windows: + + ```powershell + Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -Quality 'dev'" + ``` + + macOS/Linux: + + ```bash + curl -sSL https://aspire.dev/install.sh | bash -s -- --quality "dev" + ``` + +- Install with verbose output (Linux/macOS only): + + ```bash + curl -sSL https://aspire.dev/install.sh | bash -s -- --verbose + ``` + +## Uninstall + +There's no uninstall script. Delete the installation directory, such as `%USERPROFILE%\.aspire\bin` on Windows or `$HOME/.aspire/bin` on Linux/macOS. + +## See also + +- [Install .NET Aspire CLI](install.md) diff --git a/docs/cli/install.md b/docs/cli/install.md index e8ca9d2f9e..738f41cd7a 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -20,9 +20,33 @@ This article teaches you how to install the Aspire CLI, which is a CLI tool used ## Install as a native executable -The compiled version of the Aspire CLI can be installed using the Aspire CLI installation script. +The compiled version of the Aspire CLI can be installed using the Aspire CLI installation script. The script is available for PowerShell and Bash. -[!INCLUDE [install-aspire-cli](../includes/install-aspire-cli.md)] +01. Open a terminal. +01. Download the script and save it as a file: + + ```powershell + Invoke-RestMethod https://aspire.dev/install.ps1 -OutFile aspire-install.ps1 + ``` + + ```bash + curl -sSL https://aspire.dev/install.sh -o aspire-install.sh + ``` + +01. Run the script to install the stable release build of Aspire. + + You should see output similar to the following snippet: + + ```Output + Downloading from: https://aka.ms/dotnet/9/aspire/ga/daily/aspire-cli-win-x64.zip + Aspire CLI successfully installed to: C:\Users\name\.aspire\bin\aspire.exe + Added C:\name\adegeo\.aspire\bin to PATH for current session + Added C:\name\adegeo\.aspire\bin to user PATH environment variable + + The aspire cli is now available for use in this and new sessions. + ``` + +For more information about the install script, see [aspire-install script reference](install-script-reference.md). ## Install as a .NET global tool @@ -48,3 +72,7 @@ If that command works, you're presented with the version of the Aspire CLI tool: ```Aspire 9.4.0 ``` + +## See also + +- [aspire-install script reference](install-script-reference.md). diff --git a/docs/toc.yml b/docs/toc.yml index 758e927058..4d122a4438 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -125,6 +125,8 @@ items: href: cli/overview.md - name: Install href: cli/install.md + - name: aspire-install script reference + href: cli/install-script-reference.md - name: aspire command reference items: - name: aspire From faf13ce9a7a849db53660929c218b4ac6512e3f0 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 29 Aug 2025 11:59:41 -0700 Subject: [PATCH 2/6] Remove old install script ref include --- docs/fundamentals/setup-tooling.md | 7 +- .../build-your-first-aspire-app.md | 6 +- docs/includes/install-aspire-cli.md | 127 ------------------ 3 files changed, 7 insertions(+), 133 deletions(-) delete mode 100644 docs/includes/install-aspire-cli.md diff --git a/docs/fundamentals/setup-tooling.md b/docs/fundamentals/setup-tooling.md index 909173ba3e..16e10cc1e5 100644 --- a/docs/fundamentals/setup-tooling.md +++ b/docs/fundamentals/setup-tooling.md @@ -253,12 +253,13 @@ Once you create a new .NET Aspire project, you run and debug the app, stepping t :::zone-end -## 🖥️ Aspire CLI +## Aspire CLI -🧪 The Aspire CLI is **still in preview** and under active development. Expect more features and polish in future releases. +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. -[!INCLUDE [install-aspire-cli](../includes/install-aspire-cli.md)] +For more information, see [Aspire CLI Overview](../cli/overview.md) and [Install .NET Aspire CLI](../cli/install.md). ## See also - [Use Dev Proxy with .NET Aspire project](/microsoft-cloud/dev/dev-proxy/how-to/use-dev-proxy-with-dotnet-aspire) +- [Aspire CLI Overview](../cli/overview.md) diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md index dd14f9bb46..5ae311d36a 100644 --- a/docs/get-started/build-your-first-aspire-app.md +++ b/docs/get-started/build-your-first-aspire-app.md @@ -222,11 +222,11 @@ The preceding code: For more information, see [Make HTTP requests with the `HttpClient`](/dotnet/fundamentals/networking/http/httpclient) class. -## 🖥️ Aspire CLI +## Aspire CLI -🧪 The Aspire CLI is **still in preview** and under active development. Expect more features and polish in future releases. +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. -[!INCLUDE [install-aspire-cli](../includes/install-aspire-cli.md)] +For more information, see [Aspire CLI Overview](../cli/overview.md) and [Install .NET Aspire CLI](../cli/install.md). ## See also diff --git a/docs/includes/install-aspire-cli.md b/docs/includes/install-aspire-cli.md deleted file mode 100644 index dac344239a..0000000000 --- a/docs/includes/install-aspire-cli.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Install the Aspire CLI -ms.date: 07/25/2025 ---- - -### [Unix](#tab/unix) - -To install the Aspire CLI, run the following command in your terminal: - -```sh -curl -sSL https://aspire.dev/install.sh | bash -``` - -#### Script options - -The Unix install script (`install.sh`) supports the following options: - -| Parameter | Short form | Description | Default value | -|-----------|------------|-------------|---------------| -| `--install-path` | `-i` | Directory to install the CLI | `$HOME/.aspire/bin` | -| `--version` | | Version of the Aspire CLI to download | `9.4` | -| `--quality` | `-q` | Quality to download (`dev`, `staging`, `release`) | `release` | -| `--os` | | Operating system (auto-detected if not specified) | auto-detect | -| `--arch` | | Architecture (auto-detected if not specified) | auto-detect | -| `--keep-archive` | `-k` | Keep downloaded archive files after installation | `false` | -| `--verbose` | `-v` | Enable verbose output | `false` | -| `--help` | `-h` | Show help message | | - -#### Quality options - -The `--quality` option determines which build of the Aspire CLI to install: - -- **`dev`**: Latest builds from the `main` branch (development builds). -- **`staging`**: Builds from the current release branch (pre-release builds). -- **`release`**: Latest generally available release (stable builds). - -#### Usage examples - -Install to a custom directory: - -```sh -curl -sSL https://aspire.dev/install.sh | bash -s -- --install-path "/usr/local/bin" -``` - -Install with verbose output: - -```sh -curl -sSL https://aspire.dev/install.sh | bash -s -- --verbose -``` - -Install a specific version: - -```sh -curl -sSL https://aspire.dev/install.sh | bash -s -- --version "9.4" -``` - -Install development builds: - -```sh -curl -sSL https://aspire.dev/install.sh | bash -s -- --quality "dev" -``` - -#### Default installation path - -The script installs the Aspire CLI to `$HOME/.aspire/bin` by default. - -### [Windows](#tab/windows) - -To install the Aspire CLI, run the following command in your terminal: - -```powershell -Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) }" -``` - -#### Script options - -The Windows install script (`install.ps1`) supports the following options: - -| Parameter | Description | Default value | -|-----------|-------------|---------------| -| `-InstallPath` | Directory to install the CLI | `%USERPROFILE%\.aspire\bin` | -| `-Version` | Version of the Aspire CLI to download | `9.4` | -| `-Quality` | Quality to download (`dev`, `staging`, `release`) | `release` | -| `-OS` | Operating system (auto-detected if not specified) | auto-detect | -| `-Architecture` | Architecture (auto-detected if not specified) | auto-detect | -| `-KeepArchive` | Keep downloaded archive files after installation | `false` | -| `-Help` | Show help message | | - -#### Quality options - -The `-Quality` option determines which build of the Aspire CLI to install: - -- **`dev`**: Latest builds from the `main` branch (development builds). -- **`staging`**: Builds from the current release branch (pre-release builds). -- **`release`**: Latest generally available release (stable builds). - -#### Usage examples - -Install to a custom directory: - -```powershell -Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -InstallPath 'C:\Tools\Aspire'" -``` - -Install with verbose output: - -```powershell -Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -Verbose" -``` - -Install a specific version: - -```powershell -Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -Version '9.4'" -``` - -Install development builds: - -```powershell -Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -Quality 'dev'" -``` - -#### Default installation path - -The script installs the Aspire CLI to `%USERPROFILE%\.aspire\bin` by default. - ---- From 11b830b0f3b230d42a2b722fc42165e096b1a11b Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 29 Aug 2025 12:02:58 -0700 Subject: [PATCH 3/6] Change examples to use the script directly --- docs/cli/install-script-reference.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/cli/install-script-reference.md b/docs/cli/install-script-reference.md index 670d7d23b4..7812ecab1b 100644 --- a/docs/cli/install-script-reference.md +++ b/docs/cli/install-script-reference.md @@ -100,13 +100,13 @@ Unless changed with the `-InstallPath|--install-path` argument, the script insta Windows: ```powershell - Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) }" + .\aspire-install.ps1 ``` macOS/Linux: ```bash - curl -sSL https://aspire.dev/install.sh | bash + ./aspire-install.sh ``` - Install to a custom directory: @@ -114,13 +114,13 @@ Unless changed with the `-InstallPath|--install-path` argument, the script insta Windows: ```powershell - Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -InstallPath 'C:\Tools\Aspire'" + .\aspire-install.ps1 -InstallPath 'C:\Tools\Aspire' ``` macOS/Linux: ```bash - curl -sSL https://aspire.dev/install.sh | bash -s -- --install-path "/usr/local/bin" + ./aspire-install.sh --install-path "/usr/local/bin" ``` - Install a specific version: @@ -128,13 +128,13 @@ Unless changed with the `-InstallPath|--install-path` argument, the script insta Windows: ```powershell - Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -Version '9.4'" + .\aspire-install.ps1 -Version '9.4' ``` macOS/Linux: ```bash - curl -sSL https://aspire.dev/install.sh | bash -s -- --version "9.4" + ./aspire-install.sh --version "9.4" ``` - Install development builds: @@ -142,19 +142,19 @@ Unless changed with the `-InstallPath|--install-path` argument, the script insta Windows: ```powershell - Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) } -Quality 'dev'" + .\aspire-install.ps1 -Quality 'dev' ``` macOS/Linux: ```bash - curl -sSL https://aspire.dev/install.sh | bash -s -- --quality "dev" + ./aspire-install.sh --quality "dev" ``` - Install with verbose output (Linux/macOS only): ```bash - curl -sSL https://aspire.dev/install.sh | bash -s -- --verbose + ./aspire-install.sh --verbose ``` ## Uninstall From 256bef96a9df2669b5a1c82dd0d4daf08cc37054 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 29 Aug 2025 12:07:40 -0700 Subject: [PATCH 4/6] Add download+run example --- docs/cli/install.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/cli/install.md b/docs/cli/install.md index 738f41cd7a..ee08412171 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -4,7 +4,7 @@ description: Learn how to install .NET Aspire CLI, which is a .NET global tool. author: adegeo ms.author: adegeo ms.topic: install-set-up-deploy -ms.date: 07/24/2025 +ms.date: 08/29/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. @@ -48,6 +48,21 @@ The compiled version of the Aspire CLI can be installed using the Aspire CLI ins For more information about the install script, see [aspire-install script reference](install-script-reference.md). +> [!TIP] +> You can download and run the script in a single command: +> +> Windows: +> +> ```powershell +> Invoke-Expression "& { $(Invoke-RestMethod https://aspire.dev/install.ps1) }" +> ``` +> +> macOS/Linux: +> +> ```bash +> curl -sSL https://aspire.dev/install.sh | bash +> ``` + ## Install as a .NET global tool Use the `dotnet tool` command to install the Aspire CLI global tool. The name of the global tool is [Aspire.Cli](https://www.nuget.org/packages/Aspire.CLI). From a927644fd271377ec3e8361579737bad5ac20f8d Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 29 Aug 2025 12:11:26 -0700 Subject: [PATCH 5/6] Add link in whats new 9.4 --- docs/whats-new/dotnet-aspire-9.4.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/whats-new/dotnet-aspire-9.4.md b/docs/whats-new/dotnet-aspire-9.4.md index 5405c58738..647496097a 100644 --- a/docs/whats-new/dotnet-aspire-9.4.md +++ b/docs/whats-new/dotnet-aspire-9.4.md @@ -60,6 +60,8 @@ This will install the CLI and put it on your PATH (the binaries are placed in th dotnet tool install -g Aspire.Cli ``` +For more information, see [Install .NET Aspire CLI](../cli/install.md) and [aspire-install script reference](../cli/install-script-reference.md). + > [!NOTE] > ⚠️ **The Aspire 9.4 CLI is not compatible with Aspire 9.3 projects.** > You must upgrade your project to Aspire 9.4+ in order to use the latest CLI features. From 0df9af9d9c2e956f9099536f165874d6d67d83b9 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 29 Aug 2025 12:24:02 -0700 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/cli/install-script-reference.md | 2 +- docs/cli/install.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cli/install-script-reference.md b/docs/cli/install-script-reference.md index 7812ecab1b..372c79fecb 100644 --- a/docs/cli/install-script-reference.md +++ b/docs/cli/install-script-reference.md @@ -1,5 +1,5 @@ --- -title: Install .NET Aspire CLI +title: aspire-install script reference description: Learn about the aspire-install scripts to install the .NET Aspire CLI. Use the .NET Aspire CLI to create, run, and manage .NET Aspire projects. author: adegeo ms.author: adegeo diff --git a/docs/cli/install.md b/docs/cli/install.md index ee08412171..1b9cf3cad4 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -40,8 +40,8 @@ The compiled version of the Aspire CLI can be installed using the Aspire CLI ins ```Output Downloading from: https://aka.ms/dotnet/9/aspire/ga/daily/aspire-cli-win-x64.zip Aspire CLI successfully installed to: C:\Users\name\.aspire\bin\aspire.exe - Added C:\name\adegeo\.aspire\bin to PATH for current session - Added C:\name\adegeo\.aspire\bin to user PATH environment variable + Added C:\Users\username\.aspire\bin to PATH for current session + Added C:\Users\username\.aspire\bin to user PATH environment variable The aspire cli is now available for use in this and new sessions. ```