From af65bae78f0b8f7ec413dca1e7d019ae23356060 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Sat, 30 May 2026 04:00:37 +0000 Subject: [PATCH 1/2] Add aspire ls command reference documentation Documents the aspire ls command which discovers and lists AppHost project candidates, including: - Table and JSON output formats - Streaming mode (--format json --stream) and its ordering behavior - The --all flag for including all candidates - Configuration file path validation error messages Fixes noted in microsoft/aspire#17688 (backport of fixes L1-L5): - Stream output is emitted in arrival order (not sorted); non-streaming JSON output is sorted by path - Guidance on sorting streamed output with jq Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../config/sidebar/reference.topics.ts | 1 + .../docs/reference/cli/commands/aspire-ls.mdx | 139 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index 7f8024471..6c0e90bb5 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -434,6 +434,7 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = { slug: 'reference/cli/commands/aspire-export', }, { label: 'aspire init', slug: 'reference/cli/commands/aspire-init' }, + { label: 'aspire ls', slug: 'reference/cli/commands/aspire-ls' }, { label: 'aspire logs', slug: 'reference/cli/commands/aspire-logs', diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx new file mode 100644 index 000000000..5a584646f --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx @@ -0,0 +1,139 @@ +--- +title: aspire ls command +description: Learn about the aspire ls command which discovers and lists AppHost project candidates in the current directory and its subdirectories. +--- + +import Include from '@components/Include.astro'; + +## Name + +`aspire ls` - List AppHost project candidates. + +## Synopsis + +```bash title="Aspire CLI" +aspire ls [options] +``` + +## Description + +The `aspire ls` command discovers and lists AppHost project candidates in the current working directory and its subdirectories. It performs parallel discovery and reports results along with each candidate's programming language and build status. + +The default output is a human-readable table with the following columns: + +| Column | Description | +| ---------- | ------------------------------------------------ | +| `PATH` | The file path to the AppHost project | +| `LANGUAGE` | The programming language of the AppHost | +| `STATUS` | Build status of the AppHost candidate | + +### Discovery and configuration + +If a configuration file (for example `aspire.config.json` with `appHost.path` or a legacy `aspireSettings.json` with `appHostPath`) points to an AppHost project, that path is included as a candidate. When the configured file path is absent, contains invalid characters, or is not a JSON string, a warning is displayed. + +### Output ordering + +**Non-streaming mode** (`--format json` without `--stream`): results are sorted by path before output. + +**Streaming mode** (`--format json --stream`): results are emitted in arrival order from parallel discovery and are **not sorted**. If you need a deterministic order for streamed output, pipe through a sort step. For example: + +```bash title="Aspire CLI" +aspire ls --format json --stream | jq -s 'sort_by(.path)' +``` + +## Options + +The following options are available: + +- **`--format `** + + Output result format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. + +- **`--stream`** + + Output discovered AppHosts as newline-delimited JSON (NDJSON), emitting each candidate as soon as it is discovered. Requires `--format json`. + +- **`--all`** + + Include all candidate AppHosts, ignoring `.gitignore` and built-in directory filters. + +- + +- + +- + +- + +- + +- + +## Examples + +- List all discovered AppHost candidates in table format: + + ```bash title="Aspire CLI" + aspire ls + ``` + + Example output: + + ```text title="Output" + PATH LANGUAGE STATUS + ./src/MyApp.AppHost/MyApp.AppHost.csproj C# buildable + ./src/OtherApp.AppHost/OtherApp.AppHost.csproj C# buildable + ``` + +- Output discovered AppHosts as JSON for scripting: + + ```bash title="Aspire CLI" + aspire ls --format json + ``` + + Example output: + + ```json title="Output" + [ + { + "path": "./src/MyApp.AppHost/MyApp.AppHost.csproj", + "language": "C#", + "status": "buildable" + }, + { + "path": "./src/OtherApp.AppHost/OtherApp.AppHost.csproj", + "language": "C#", + "status": "buildable" + } + ] + ``` + +- Stream discovered AppHosts as newline-delimited JSON: + + ```bash title="Aspire CLI" + aspire ls --format json --stream + ``` + + Example output (each line is a JSON object emitted as candidates are discovered): + + ```text title="Output" + {"path":"./src/OtherApp.AppHost/OtherApp.AppHost.csproj","language":"C#","status":"buildable"} + {"path":"./src/MyApp.AppHost/MyApp.AppHost.csproj","language":"C#","status":"buildable"} + ``` + + Note: lines are emitted in discovery arrival order and are not sorted. To sort streamed output by path: + + ```bash title="Aspire CLI" + aspire ls --format json --stream | jq -s 'sort_by(.path)' + ``` + +- Include all AppHost candidates, ignoring `.gitignore` and directory filters: + + ```bash title="Aspire CLI" + aspire ls --all + ``` + +## See also + +- [aspire run](/reference/cli/commands/aspire-run/) +- [aspire ps](/reference/cli/commands/aspire-ps/) From 93f8514757ef124c648a5c83512dbd06b69f49c2 Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Sat, 30 May 2026 07:47:05 -0500 Subject: [PATCH 2/2] Address review feedback (6 threads) - PRRT_kwDOQK_VN86F1phr: fixed the legacy settings file path. - PRRT_kwDOQK_VN86F120z: clarified configured AppHost path warning, error, and silent behavior. - PRRT_kwDOQK_VN86F1202: updated table and JSON examples to use raw language IDs. - PRRT_kwDOQK_VN86F1203: updated NDJSON examples to use raw language IDs and clarify variable line order. - IC_kwDOQK_VN88AAAABESVofw: added an SEO title override that satisfies the title-length guard. - PRR_kwDOQK_VN88AAAABBe3Z_A: added status values, --all filter scope, an AppHost concept link, and jq context. Verified against microsoft/aspire@11bea2eb9fbb655614bcf9814c55c88a3fdd1126 on branch release/13.4. Edited per the doc-writer skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/reference/cli/commands/aspire-ls.mdx | 39 +++++++++++-------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx index 5a584646f..f9fc63cb7 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx @@ -1,5 +1,6 @@ --- title: aspire ls command +seoTitle: aspire ls CLI command reference for discovering AppHosts description: Learn about the aspire ls command which discovers and lists AppHost project candidates in the current directory and its subdirectories. --- @@ -17,19 +18,21 @@ aspire ls [options] ## Description -The `aspire ls` command discovers and lists AppHost project candidates in the current working directory and its subdirectories. It performs parallel discovery and reports results along with each candidate's programming language and build status. +The `aspire ls` command discovers and lists [AppHost project](/get-started/app-host/) candidates in the current working directory and its subdirectories. It performs parallel discovery and reports results along with each candidate's programming language and build status. The default output is a human-readable table with the following columns: -| Column | Description | -| ---------- | ------------------------------------------------ | -| `PATH` | The file path to the AppHost project | -| `LANGUAGE` | The programming language of the AppHost | -| `STATUS` | Build status of the AppHost candidate | +| Column | Description | +| ---------- | --------------------------------------------------------------------------------- | +| `PATH` | The file path to the AppHost project | +| `LANGUAGE` | The raw AppHost language ID, such as `csharp` or `typescript/nodejs` | +| `STATUS` | Build status of the AppHost candidate: `buildable` or `possibly-unbuildable` | + +The `STATUS` value is `buildable` when the project validates as an AppHost candidate. It is `possibly-unbuildable` when the project looks like an AppHost but may not build in the current environment. ### Discovery and configuration -If a configuration file (for example `aspire.config.json` with `appHost.path` or a legacy `aspireSettings.json` with `appHostPath`) points to an AppHost project, that path is included as a candidate. When the configured file path is absent, contains invalid characters, or is not a JSON string, a warning is displayed. +If a configuration file (for example `aspire.config.json` with `appHost.path` or a legacy `.aspire/settings.json` with `appHostPath`) points to an AppHost project, that path is included as a candidate. When a configured AppHost path points to a missing file, `aspire ls` displays a warning. When the configuration file is invalid JSON, has an invalid shape, or the configured AppHost path is empty, contains invalid characters, or isn't a JSON string, `aspire ls` displays an error. When no configuration file is present, discovery continues silently. ### Output ordering @@ -41,6 +44,8 @@ If a configuration file (for example `aspire.config.json` with `appHost.path` or aspire ls --format json --stream | jq -s 'sort_by(.path)' ``` +This example uses [jq](https://jqlang.org/), a third-party JSON processor. + ## Options The following options are available: @@ -55,7 +60,7 @@ The following options are available: - **`--all`** - Include all candidate AppHosts, ignoring `.gitignore` and built-in directory filters. + Include all candidate AppHosts by disabling Git filtering and the built-in skip list for common dependency, build-output, and tooling directories such as `bin`, `obj`, `node_modules`, `.venv`, `.git`, and `.vs`. The NuGet package cache is still excluded. - @@ -80,9 +85,9 @@ The following options are available: Example output: ```text title="Output" - PATH LANGUAGE STATUS - ./src/MyApp.AppHost/MyApp.AppHost.csproj C# buildable - ./src/OtherApp.AppHost/OtherApp.AppHost.csproj C# buildable + PATH LANGUAGE STATUS + ./src/MyApp.AppHost/MyApp.AppHost.csproj csharp buildable + ./src/OtherApp.AppHost/apphost.ts typescript/nodejs buildable ``` - Output discovered AppHosts as JSON for scripting: @@ -97,12 +102,12 @@ The following options are available: [ { "path": "./src/MyApp.AppHost/MyApp.AppHost.csproj", - "language": "C#", + "language": "csharp", "status": "buildable" }, { - "path": "./src/OtherApp.AppHost/OtherApp.AppHost.csproj", - "language": "C#", + "path": "./src/OtherApp.AppHost/apphost.ts", + "language": "typescript/nodejs", "status": "buildable" } ] @@ -114,11 +119,11 @@ The following options are available: aspire ls --format json --stream ``` - Example output (each line is a JSON object emitted as candidates are discovered): + Example output (each line is a JSON object emitted as candidates are discovered; your line order may vary): ```text title="Output" - {"path":"./src/OtherApp.AppHost/OtherApp.AppHost.csproj","language":"C#","status":"buildable"} - {"path":"./src/MyApp.AppHost/MyApp.AppHost.csproj","language":"C#","status":"buildable"} + {"path":"./src/OtherApp.AppHost/apphost.ts","language":"typescript/nodejs","status":"buildable"} + {"path":"./src/MyApp.AppHost/MyApp.AppHost.csproj","language":"csharp","status":"buildable"} ``` Note: lines are emitted in discovery arrival order and are not sorted. To sort streamed output by path: