Initial drafts of .NET Aspire CLI docs

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.3.1 and later versions
+
+## Name
+
+`aspire add` - Add an integration to the Aspire project.
+
+## Synopsis
+
+```dotnetcli
+aspire add [<integration>] [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
+  ```

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.3.1 and later versions
+
+## Name
+
+`aspire exec` - Run an Aspire app host to execute a command against the resource.
+
+## Synopsis
+
+```dotnetcli
+aspire exec [options] [[--] <additional arguments>...]]
+```
+
+## Description
+
+The `aspire exec` command runs an apphost project and sends the provided commands to 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
+  ```

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.3.1 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
+  ```

docs/cli-reference/aspire-run.md

@@ -0,0 +1,92 @@
+---
+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.3.1 and later versions
+
+## Name
+
+`aspire run` - Run an Aspire app host in development mode.
+
+## Synopsis
+
+```dotnetcli
+aspire run [options] [[--] <additional arguments>...]]
+```
+
+## Description
+
+The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal-based version dashboard is also visible.
+
+[!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)]
+
+The command performs the following steps to run an apphost project:
+
+- Writes the apphost project path to the `.aspire/settings.json` config file in the current directory.
+- Installs or verifies that Aspires local hosting certificates are installed and trusted.
+- Builds the apphost project.
+- Starts the apphost.
+- Starts the dashboard.
+- Displays a terminal-based dashboard.
+
+<!-- Add asciinema here instead of the terminal dashboard -->
+
+The following snippet is an example of the terminal dashboard:
+
+```Aspire CLI
+Dashboard:
+📈  Direct: https://localhost:17077/login?t=64ebc6d760ab2c48df93607fd431cf0b
+
+╭─────────────┬─────────┬─────────┬────────────────────────╮
+│ 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 apphost and exit.
+```
+
+## Options
+
+The following options are available:
+
+- **`--`**
+
+  Delimits arguments to aspire run from arguments for the apphost being run. All arguments after this delimiter are passed to the apphost 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
+  ```

docs/cli-reference/aspire.md

@@ -0,0 +1,61 @@
+---
+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.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`.
+
+- [!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
+
+| Command                               | Status  | Function                                                                 |
+|---------------------------------------|---------|--------------------------------------------------------------------------|
+| [`aspire add`](aspire-add.md)         | Stable  | Add an integration to the Aspire project.                                |
+| [`aspire new`](aspire-new.md)         | Stable  | Create an Aspire sample project from a template.                         |
+| [`aspire run`](aspire-run.md)         | Stable  | Run an Aspire apphost in development mode.                               |
+| [`aspire exec`](aspire-exec.md)       | Preview | Similar to the `aspire run` command, but passes commands to the apphost. |
+| [`aspire deploy`](aspire-deploy.md)   | Preview | Deploys the artifacts created by `aspire publish`.                       |
+| [`aspire publish`](aspire-publish.md) | Preview | Generates deployment artifacts for an Aspire apphost project.            |
+
+## Examples
+
+- Create an Aspire solution from the template:
+
+  ```Command
+  aspire new aspire-starter
+  ```
+
+- Run an Aspire AppHost project:
+
+  ```Command
+  aspire run
+  ```

docs/cli-reference/includes/option-debug.md

@@ -0,0 +1,9 @@
+---
+title: aspire command
+description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage.
+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.

docs/cli-reference/includes/option-help.md

@@ -0,0 +1,9 @@
+---
+title: aspire command
+description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage.
+ms.date: 07/11/2025
+ms.topic: include
+---
+**`-?, -h, --help`**
+
+  Prints help and usage documentation for the available commands and options.

docs/cli-reference/includes/option-project.md

@@ -0,0 +1,9 @@
+---
+title: aspire command
+description: Learn about the aspire command (the generic driver for the Aspire CLI) and its usage.
+ms.date: 07/11/2025
+ms.topic: include
+---
+**`--project`**
+
+  The path to the Aspire apphost project file.