From 3734d98df4357ce87633a1a3155133b74ea67c11 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 02:05:16 +0000 Subject: [PATCH 1/6] Initial plan From 923472ee3776e136544173e03ce0c3db5d8e48f5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 02:13:23 +0000 Subject: [PATCH 2/6] Add aspire describe command documentation (renamed from aspire resources) Addresses #461: CLI aspire resources renamed to aspire describe with --watch renamed to --follow/-f. Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../config/sidebar/reference.topics.ts | 4 + .../cli/commands/aspire-describe.mdx | 122 ++++++++++++++++++ .../docs/reference/cli/commands/aspire.mdx | 1 + .../content/docs/reference/cli/overview.mdx | 8 ++ 4 files changed, 135 insertions(+) create mode 100644 src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index dc7c9a3e8..9f9d4bb3c 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -328,6 +328,10 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig = { label: 'aspire doctor', slug: 'reference/cli/commands/aspire-doctor', }, + { + label: 'aspire describe', + slug: 'reference/cli/commands/aspire-describe', + }, { label: 'aspire exec', slug: 'reference/cli/commands/aspire-exec' }, { label: 'aspire init', slug: 'reference/cli/commands/aspire-init' }, { diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx new file mode 100644 index 000000000..22761d155 --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx @@ -0,0 +1,122 @@ +--- +title: aspire describe command +description: Learn about the aspire describe command which displays resource details for a running Aspire AppHost, with optional continuous streaming. +--- + +import Include from '@components/Include.astro'; +import { Aside } from '@astrojs/starlight/components'; + +## Name + +`aspire describe` - Describe resources in a running AppHost. + +## Synopsis + +```bash title="Aspire CLI" +aspire describe [] [options] +``` + +## Description + +The `aspire describe` command displays resource details for a running Aspire AppHost. By default, it shows a snapshot table of all resources with their name, type, state, health status, and endpoints. Use the `--follow` option to continuously stream resource state changes in real time. + +When a specific resource name is provided, only matching resources are displayed. If no matching resource is found, the command returns an error. + +When executed without the `--apphost` option, the command: + +1. Scans for all running AppHost processes. +2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target. +3. If only one AppHost is running in scope, connects to it directly. +4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. + + + +## Arguments + +- **``** + + The name of the resource to display. If not specified, all resources are shown. + +## Options + +The following options are available: + +- **`-f, --follow`** + + Continuously stream resource state changes. In table mode, each update prints a line showing the resource name, state, health, and endpoints. In JSON mode, each update emits a single JSON object per line (NDJSON format). + +- **`--apphost `** + + The path to the Aspire AppHost project file. When specified, the command connects to the AppHost running from that project file without prompting for selection. + +- **`--format `** + + Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. + + In snapshot mode (without `--follow`), JSON output wraps resources in a `{ "resources": [...] }` object. In follow mode, JSON output uses NDJSON (one JSON object per line) for streaming. + +- + +- + +## Examples + +- Show all resources in a running AppHost: + + ```bash title="Aspire CLI" + aspire describe + ``` + + Example output: + + ```text title="Output" + Name Type State Health Endpoints + cache container Running Healthy tcp://localhost:63122 + webfrontend project Running Healthy https://localhost:17015, http://localhost:15099 + apiservice project Running Healthy https://localhost:17016, http://localhost:15100 + ``` + +- Show details for a specific resource: + + ```bash title="Aspire CLI" + aspire describe webfrontend + ``` + +- Continuously stream resource state changes: + + ```bash title="Aspire CLI" + aspire describe --follow + ``` + +- Stream state changes for a specific resource: + + ```bash title="Aspire CLI" + aspire describe webfrontend --follow + ``` + +- Output resource details as JSON: + + ```bash title="Aspire CLI" + aspire describe --format Json + ``` + +- Stream resource changes as NDJSON for scripting: + + ```bash title="Aspire CLI" + aspire describe --follow --format Json + ``` + +- Target a specific AppHost project: + + ```bash title="Aspire CLI" + aspire describe --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' + ``` + +## See also + +- [aspire run](/reference/cli/commands/aspire-run/) +- [aspire ps](/reference/cli/commands/aspire-ps/) +- [aspire wait](/reference/cli/commands/aspire-wait/) +- [aspire stop](/reference/cli/commands/aspire-stop/) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire.mdx index cf6e84ded..9e943577c 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire.mdx @@ -45,6 +45,7 @@ The following commands are available: | [`aspire cache`](../aspire-cache/) | Stable | Manage disk cache for CLI operations. | | [`aspire config`](../aspire-config/) | Stable | Configures the Aspire environment. | | [`aspire deploy`](../aspire-deploy/) | Preview | Deploys the artifacts created by `aspire publish`. | +| [`aspire describe`](../aspire-describe/) | Stable | Describe resources in a running AppHost. | | [`aspire do`](../aspire-do/) | Preview | Execute a specific pipeline step and its dependencies. | | [`aspire docs`](../aspire-docs/) | Stable | Browse and search Aspire documentation from aspire.dev. | | [`aspire doctor`](../aspire-doctor/) | Stable | Check the development environment for common issues. | diff --git a/src/frontend/src/content/docs/reference/cli/overview.mdx b/src/frontend/src/content/docs/reference/cli/overview.mdx index b62d52bf9..e6274c591 100644 --- a/src/frontend/src/content/docs/reference/cli/overview.mdx +++ b/src/frontend/src/content/docs/reference/cli/overview.mdx @@ -151,6 +151,14 @@ The `aspire exec` command runs a command in the context of a specific Aspire res [Command reference: `aspire exec`](../commands/aspire-exec/) +## Describe resources + +The `aspire describe` command displays resource details for a running Aspire AppHost, including name, type, state, health status, and endpoints. Use it to get a quick snapshot of all resources or continuously stream state changes with the `--follow` flag. + + + [Command reference: `aspire describe`](../commands/aspire-describe/) + + ## Manage CLI configuration The `aspire config` command lets you manage Aspire CLI configuration settings. Use it to `list`, `get`, `set`, or `delete` configuration values that control CLI behavior. This command is also used to toggle features on or off. From 981284ff1d5e6e5b3ffa7dd216e0b122c5717576 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 02:14:13 +0000 Subject: [PATCH 3/6] Fix alphabetical ordering of aspire describe in sidebar Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- src/frontend/config/sidebar/reference.topics.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index 9f9d4bb3c..b9d35f8c6 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -301,6 +301,10 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig = { label: 'aspire deploy', slug: 'reference/cli/commands/aspire-deploy', }, + { + label: 'aspire describe', + slug: 'reference/cli/commands/aspire-describe', + }, { label: 'aspire do', slug: 'reference/cli/commands/aspire-do' }, { label: 'aspire docs', @@ -328,10 +332,6 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig = { label: 'aspire doctor', slug: 'reference/cli/commands/aspire-doctor', }, - { - label: 'aspire describe', - slug: 'reference/cli/commands/aspire-describe', - }, { label: 'aspire exec', slug: 'reference/cli/commands/aspire-exec' }, { label: 'aspire init', slug: 'reference/cli/commands/aspire-init' }, { From 3531b212b6f738b4e0c135e35e2af558d142ad3b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 03:05:58 +0000 Subject: [PATCH 4/6] Address review feedback: wrap Steps, expand NDJSON, add what's new entry - Wrap numbered list in Steps component per review feedback - Expand NDJSON acronym to Newline Delimited JSON with links - Add 'Resource monitoring with aspire describe' section to what's new 13.2 Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../reference/cli/commands/aspire-describe.mdx | 12 ++++++++---- .../src/content/docs/whats-new/aspire-13-2.mdx | 16 ++++++++++++++++ 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx index 22761d155..6bbffc51a 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx @@ -4,7 +4,7 @@ description: Learn about the aspire describe command which displays resource det --- import Include from '@components/Include.astro'; -import { Aside } from '@astrojs/starlight/components'; +import { Aside, Steps } from '@astrojs/starlight/components'; ## Name @@ -24,11 +24,15 @@ When a specific resource name is provided, only matching resources are displayed When executed without the `--apphost` option, the command: + + 1. Scans for all running AppHost processes. 2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target. 3. If only one AppHost is running in scope, connects to it directly. 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. + + @@ -45,7 +49,7 @@ The following options are available: - **`-f, --follow`** - Continuously stream resource state changes. In table mode, each update prints a line showing the resource name, state, health, and endpoints. In JSON mode, each update emits a single JSON object per line (NDJSON format). + Continuously stream resource state changes. In table mode, each update prints a line showing the resource name, state, health, and endpoints. In JSON mode, each update emits a single JSON object per line ([Newline Delimited JSON (NDJSON)](http://ndjson.org/) format). - **`--apphost `** @@ -55,7 +59,7 @@ The following options are available: Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. - In snapshot mode (without `--follow`), JSON output wraps resources in a `{ "resources": [...] }` object. In follow mode, JSON output uses NDJSON (one JSON object per line) for streaming. + In snapshot mode (without `--follow`), JSON output wraps resources in a `{ "resources": [...] }` object. In follow mode, JSON output uses [Newline Delimited JSON (NDJSON)](http://ndjson.org/) for streaming, emitting one JSON object per line. - @@ -102,7 +106,7 @@ The following options are available: aspire describe --format Json ``` -- Stream resource changes as NDJSON for scripting: +- Stream resource changes as Newline Delimited JSON (NDJSON) for scripting: ```bash title="Aspire CLI" aspire describe --follow --format Json diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx index c7173b50e..f45823855 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx @@ -124,6 +124,22 @@ aspire run --isolated Isolated mode assigns random ports and creates separate user secrets for each run, preventing port conflicts and configuration collisions. This is particularly useful when switching between different Aspire projects or running integration tests that need dedicated ports. +### Resource monitoring with `aspire describe` + +The `aspire resources` command has been renamed to `aspire describe` (with `resources` kept as a backward-compatible alias) to better align with `kubectl`-style conventions. The `--watch` flag has also been renamed to `--follow`/`-f` for consistency with `aspire logs --follow`. + +```bash title="Aspire CLI — Describe resources" +# Show all resources in a running AppHost +aspire describe + +# Continuously stream resource state changes +aspire describe --follow +``` + + + Command reference: [`aspire describe`](/reference/cli/commands/aspire-describe/). + + ### Environment diagnostics with `aspire doctor` The new `aspire doctor` command provides comprehensive diagnostics of your development environment: From 8f50ee53464ffaad7f3a70045d4a17ecdec0a053 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 13:23:04 +0000 Subject: [PATCH 5/6] Add case-insensitive note to --format option Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../src/content/docs/reference/cli/commands/aspire-describe.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx index 6bbffc51a..b2ef2ad06 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx @@ -57,7 +57,7 @@ The following options are available: - **`--format `** - Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. + Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. Values are case-insensitive. In snapshot mode (without `--follow`), JSON output wraps resources in a `{ "resources": [...] }` object. In follow mode, JSON output uses [Newline Delimited JSON (NDJSON)](http://ndjson.org/) for streaming, emitting one JSON object per line. From 7e8b18188be7703b06f7b2473ae6fc9ccb834e5a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 13:26:20 +0000 Subject: [PATCH 6/6] Replace ndjson.org links with GitHub spec repo Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../content/docs/reference/cli/commands/aspire-describe.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx index b2ef2ad06..41f340f10 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx @@ -49,7 +49,7 @@ The following options are available: - **`-f, --follow`** - Continuously stream resource state changes. In table mode, each update prints a line showing the resource name, state, health, and endpoints. In JSON mode, each update emits a single JSON object per line ([Newline Delimited JSON (NDJSON)](http://ndjson.org/) format). + Continuously stream resource state changes. In table mode, each update prints a line showing the resource name, state, health, and endpoints. In JSON mode, each update emits a single JSON object per line ([Newline Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec) format). - **`--apphost `** @@ -59,7 +59,7 @@ The following options are available: Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. Values are case-insensitive. - In snapshot mode (without `--follow`), JSON output wraps resources in a `{ "resources": [...] }` object. In follow mode, JSON output uses [Newline Delimited JSON (NDJSON)](http://ndjson.org/) for streaming, emitting one JSON object per line. + In snapshot mode (without `--follow`), JSON output wraps resources in a `{ "resources": [...] }` object. In follow mode, JSON output uses [Newline Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec) for streaming, emitting one JSON object per line. -