Rewrite the install script reference

docs/cli/install-script-reference.md

@@ -0,0 +1,166 @@
+---
+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
+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 <DIRECTORY>] [-Version <VERSION>] [-Quality <QUALITY>]
+                   [-OS <OPERATING_SYSTEM>] [-Architecture <ARCHITECTURE>] [-KeepArchive] [-Help]"
+```
+
+Linux/macOS:
+
+```bash
+aspire-install.sh [--install-path <DIRECTORY>] [--version <VERSION>] [--quality <QUALITY>]
+                  [--os <OPERATING_SYSTEM>] [--arch <ARCHITECTURE>] [--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 <DIRECTORY>`**
+
+  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 <VERSION>`**
+
+  Represents a specific version to install. For example: `9.4`. If not specified, the latest stable version is installed.
+
+- **`-Quality|--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 <OPERATING_SYSTEM>`**
+
+  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>`**
+
+  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
+  .\aspire-install.ps1
+  ```
+
+  macOS/Linux:
+
+  ```bash
+  ./aspire-install.sh
+  ```
+
+- Install to a custom directory:
+
+  Windows:
+
+  ```powershell
+  .\aspire-install.ps1 -InstallPath 'C:\Tools\Aspire'
+  ```
+
+  macOS/Linux:
+
+  ```bash
+  ./aspire-install.sh --install-path "/usr/local/bin"
+  ```
+
+- Install a specific version:
+
+  Windows:
+
+  ```powershell
+  .\aspire-install.ps1 -Version '9.4'
+  ```
+
+  macOS/Linux:
+
+  ```bash
+  ./aspire-install.sh --version "9.4"
+  ```
+
+- Install development builds:
+
+  Windows:
+
+  ```powershell
+  .\aspire-install.ps1 -Quality 'dev'
+  ```
+
+  macOS/Linux:
+
+  ```bash
+  ./aspire-install.sh --quality "dev"
+  ```
+
+- Install with verbose output (Linux/macOS only):
+
+  ```bash
+  ./aspire-install.sh --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)

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.
 
@@ -20,9 +20,48 @@ 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:\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.
+    ```
+
+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
 
@@ -48,3 +87,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).

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)

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