[Docs][13.3] CLI: missing conceptual documentation for 12 new APIs/behaviors

[joperezr]

Aspire 13.3 — CLI conceptual docs gap

This issue tracks 12 CLI changes shipped in Aspire 13.3 that introduce new APIs, behaviors, or user-visible surfaces with no conceptual documentation in microsoft/aspire.dev. This issue is scoped to the missing conceptual docs only — the What's New release-notes entries are being handled separately.

Source: 13.3 Change log wiki. Audit performed against release/13.3.

The Owner column is the author of the source PR (or first-write-access author if multiple); contributor-only rows are unowned and need to be picked up by the team. Use the Progress checklist below the table to mark items done — GitHub doesn't render checkable checkboxes inside table cells, so the checklist is separate.

Items needing docs

#	Title	Type	Source PR(s)	Suggested doc location	Owner
1	Aspire CLI available as a dotnet tool	feature	#16496, #16611	get-started/install-cli.mdx	@radical
2	List pipeline steps without running them (--list-steps flag)	feature	#16085	reference/cli/commands/aspire-publish.mdx + aspire-deploy.mdx (extend)	@mitchdenny
3	New aspire destroy command	feature	#16097	reference/cli/commands/aspire-destroy.mdx (new)	@davidfowl
4	Connect CLI and MCP to standalone Aspire Dashboard (--dashboard-url, --api-key)	feature	#15595	reference/cli/commands/aspire-run.mdx + dashboard/standalone.mdx	@JamesNK
5	Java polyglot AppHost support improvements (experimental)	feature	#15470, #15636	integrations/frameworks/java.mdx (or similar)	@sebastienros
6	Improved AI agent init with location selection and standard skill support	feature	#15022, #15640	reference/cli/commands/aspire-agent-init.mdx (extend)	@IEvangelist, @JamesNK
7	CLI telemetry JSON output aligned with MCP tool format	improvement	#16523	reference/cli/telemetry.mdx (or similar)	@JamesNK
8	AppHost path guardrails in global config	improvement	#16467	get-started/install-cli.mdx	@adamint
9	Container runtime health check before deploy (check-container-runtime)	improvement	#16196	reference/cli/commands/aspire-deploy.mdx (extend)	@davidfowl
10	Hidden resources filtered by default in CLI commands (--include-hidden)	improvement	#16146	reference/cli/commands/aspire-ps.mdx + aspire-describe.mdx	@JamesNK
11	Publish summary with hierarchy and timeline view	improvement	#15530	reference/cli/commands/aspire-publish.mdx + aspire-deploy.mdx	@sebastienros
12	Python starter template migrated to CLI template factory	improvement	#15574	get-started/aspire-sdk-templates.mdx	@davidfowl

Progress checklist

• 1. Aspire CLI available as a dotnet tool — @radical
• 2. List pipeline steps without running them (--list-steps flag) [docs] Document --list-steps and --no-build pipeline options #801 [docs] Add --list-steps sample output to aspire do and pipelines pages #847 — @mitchdenny
• 3. New aspire destroy command — @davidfowl
• 4. Connect CLI and MCP to standalone Aspire Dashboard (--dashboard-url, --api-key) — @JamesNK
• 5. Java polyglot AppHost support improvements (experimental) — @sebastienros
• 6. Improved AI agent init with location selection and standard skill support — @IEvangelist, @JamesNK
• 7. CLI telemetry JSON output aligned with MCP tool format — @JamesNK
• 8. AppHost path guardrails in global config — @adamint
• 9. Container runtime health check before deploy (check-container-runtime) — @davidfowl
• 10. Hidden resources filtered by default in CLI commands (--include-hidden) — @JamesNK
• 11. Publish summary with hierarchy and timeline view Document publish summary output #844 — @sebastienros
• 12. Python starter template migrated to CLI template factory — @davidfowl

Per-item rationale and content guidance

1. Aspire CLI available as a dotnet tool

• Type: feature
• Source PR(s): #16496, #16611
• Where to add docs: get-started/install-cli.mdx
• Why it needs docs / what to cover: install-cli.mdx does not document the new "dotnet tool install -g Aspire.Cli" path. Need to add it as a supported install method + What's New entry.

2. List pipeline steps without running them (--list-steps flag)

• Type: feature
• Source PR(s): #16085
• Where to add docs: reference/cli/commands/aspire-publish.mdx + aspire-deploy.mdx (extend)
• Why it needs docs / what to cover: --list-steps flag not documented in CLI reference.

3. New aspire destroy command

• Type: feature
• Source PR(s): #16097
• Where to add docs: reference/cli/commands/aspire-destroy.mdx (new)
• Why it needs docs / what to cover: No reference/cli/commands/aspire-destroy.mdx page exists; only mentioned in body of other pages. Need full CLI reference page + What's New entry.

4. Connect CLI and MCP to standalone Aspire Dashboard (--dashboard-url, --api-key)

• Type: feature
• Source PR(s): #15595
• Where to add docs: reference/cli/commands/aspire-run.mdx + dashboard/standalone.mdx
• Why it needs docs / what to cover: --dashboard-url and --api-key flags for connecting CLI/MCP to standalone dashboard not documented.

5. Java polyglot AppHost support improvements (experimental)

• Type: feature
• Source PR(s): #15470, #15636
• Where to add docs: integrations/frameworks/java.mdx (or similar)
• Why it needs docs / what to cover: Java polyglot AppHost (experimental) not documented despite TS/Python being documented.

6. Improved AI agent init with location selection and standard skill support

• Type: feature
• Source PR(s): #15022, #15640
• Where to add docs: reference/cli/commands/aspire-agent-init.mdx (extend)
• Why it needs docs / what to cover: New AI agent init flow (location selection, standard skill support) not documented.

7. CLI telemetry JSON output aligned with MCP tool format

• Type: improvement
• Source PR(s): #16523
• Where to add docs: reference/cli/telemetry.mdx (or similar)
• Why it needs docs / what to cover: CLI telemetry JSON output format aligned to MCP — breaking change for any consumers, plus needs release notes.

8. AppHost path guardrails in global config

• Type: improvement
• Source PR(s): #16467
• Where to add docs: get-started/install-cli.mdx
• Why it needs docs / what to cover: AppHost path guardrails in global config — behavior change for CLI users.

9. Container runtime health check before deploy (check-container-runtime)

• Type: improvement
• Source PR(s): #16196
• Where to add docs: reference/cli/commands/aspire-deploy.mdx (extend)
• Why it needs docs / what to cover: New check-container-runtime pipeline step — should document.

10. Hidden resources filtered by default in CLI commands (--include-hidden)

• Type: improvement
• Source PR(s): #16146
• Where to add docs: reference/cli/commands/aspire-ps.mdx + aspire-describe.mdx
• Why it needs docs / what to cover: Hidden resources filtered by default; --include-hidden flag — needs CLI ref updates.

11. Publish summary with hierarchy and timeline view

• Type: improvement
• Source PR(s): #15530
• Where to add docs: reference/cli/commands/aspire-publish.mdx + aspire-deploy.mdx
• Why it needs docs / what to cover: Publish summary with hierarchy and timeline view — should document new output format.

12. Python starter template migrated to CLI template factory

• Type: improvement
• Source PR(s): #15574
• Where to add docs: get-started/aspire-sdk-templates.mdx
• Why it needs docs / what to cover: Python starter template now in CLI template factory — should reference if applicable.

---

This issue was generated from a structured audit of the 13.3 changelog against the release/13.3 branch of aspire.dev.