arisng Aspire CLI
Use this skill to choose the right Aspire workflow, keep long-running processes under Aspire's control, and combine AppHost source, official docs lookup, CLI inspection, MCP tools, and browser automation into a tight agent loop.
Fast path
- Identify the goal: scaffold, adopt, configure agents, browse official docs, start attached or detached, inspect, debug, manage resources, update, or publish/deploy.
- Confirm context: AppHost path, single vs multiple AppHosts, human-interactive vs automation, single instance vs parallel worktrees.
- Prefer the smallest reliable surface:
aspire doctorfor environment issues.aspire agent initfor agent setup.aspire docs list,aspire docs search, andaspire docs getbefore unfamiliar integrations, custom dashboard or resource commands, or AppHost APIs.- MCP
list_docs,search_docs, andget_docwhen the Aspire MCP server already exposes docs tools in the current agent session. aspire runfor attached interactive sessions.aspire startfor background or delegated sessions.aspire run --isolatedoraspire start --isolatedfor parallel worktrees, background agents, or side-by-side validation.aspire describe,aspire logs,aspire otel,aspire wait, andaspire resourcefor CLI-first inspection and control.- MCP tools when the Aspire MCP server is already configured and runtime access is needed from the agent.
- Read the AppHost source before changing orchestration. The AppHost is the topology source of truth.
- Load only the reference files that match the task.
Load this reference when...
| Need | Use |
|---|---|
| Command selection, flags, and automation-friendly patterns | CLI commands overview |
| Official docs lookup, docs-first edits, and CLI/MCP docs parity | Docs lookup workflows |
| Current 13.2 command surface, renames, and migration notes | Aspire 13.2 CLI notes |
| AppHost-first agent loop, docs-first editing, telemetry guidance, and Playwright pairing | Agentic development with Aspire |
| Adding Aspire to an existing solution | App adoption patterns |
| CLI and MCP runtime access, resource discovery, and agent wiring | Aspire agent integration and resource access |
| Parallel worktrees, multi-instance AppHosts, or isolated mode | Aspire isolation |
| HTTPS certificate cleanup or trust issues | HTTPS certificate management |
| Choosing Aspire testing vs browser-driven testing | Aspire testing vs Playwright CLI |
Decision guide
| Goal | Default workflow |
|---|---|
| Create a new Aspire solution | aspire new |
| Add Aspire to an existing solution | aspire init -> wire AppHost -> aspire run |
| Set up AI coding agents | aspire agent init |
| Browse available Aspire docs | aspire docs list |
| Find official guidance for a feature or API | aspire docs search <topic> |
| Read the selected page or section | aspire docs get <slug> or aspire docs get <slug> --section "<heading>" |
| Look up docs through MCP when already connected | list_docs, search_docs, get_doc |
| Add an integration after confirming the supported pattern | aspire add <name-or-id> |
| Start in foreground | aspire run |
| Start in background | aspire start |
| Run multiple copies safely | aspire run --isolated or aspire start --isolated |
| Inspect resources and endpoints | aspire describe or MCP list_resources |
| Read logs and telemetry | aspire logs, aspire otel, or MCP log/trace tools |
| Wait for readiness in automation | aspire wait <resource> |
| Restart a single resource | aspire resource <resource> restart |
| Restore integrations or generated SDKs | aspire restore |
| Publish or deploy | aspire publish, aspire deploy, aspire do ... |
Agentic development workflow
- Run
aspire doctorwhen the environment, certificates, container runtime, or SDK look suspect. - Read the AppHost source to understand resources, references, parameters, and startup order.
- Run
aspire agent initif the repo does not already have Aspire agent configuration. - Before editing the AppHost for an unfamiliar integration, custom command, or API:
- use
aspire docs listwhen the right page or slug is unclear - use
aspire docs search <topic>and thenaspire docs get <slug>to confirm the documented pattern - if Aspire MCP docs tools are already available,
list_docs,search_docs, andget_docare equivalent entry points to the same official docs
- use
- Start the app:
aspire runfor an attached local debugging loop.aspire start --format Jsonfor background or delegated sessions.- Add
--isolatedwhen another worktree, agent, or test run may start the same AppHost.
- Inspect runtime state with
aspire describe,aspire logs,aspire otel,aspire wait, or MCP tools. - Apply code changes. For integrations or custom commands, use
aspire add <name-or-id>or edit the AppHost only after docs confirm the supported pattern, then restart only the affected resource withaspire resource <name> restartwhen possible. - For UI validation, discover the live endpoint via Aspire, then load the
playwright-cliskill to drive the browser. - Use telemetry to close the loop: build -> start -> inspect -> browser-check -> fix -> restart -> retest.
Guardrails
- Do not guess topology from ad hoc scripts if an AppHost exists; read the AppHost source.
- Do not guess integration names, custom resource command shapes, or unfamiliar AppHost APIs; use
aspire docs searchandaspire docs getfirst. - Use
aspire docs listwhen the right page or slug is unclear. - Prefer official
aspire.devdocs surfaced through Aspire CLI or MCP over memory or third-party pages. - If Aspire MCP docs tools are already available, treat
list_docs,search_docs, andget_docas first-class entry points to the same official docs. - Do not hardcode ports; use
aspire describeor MCPlist_resources. - Do not scrape the dashboard when CLI or MCP already exposes structured output.
- Do not make the agent babysit several long-running dev servers when Aspire can manage them as one AppHost.
- Use
--isolatedwhenever two copies of the same AppHost may run at once. - Use
--format Jsonand--non-interactivefor automation and agent-driven flows, and use--sectionwhen one part of a doc page is enough. - Prefer AppHost parameters and Aspire user secrets over committing secrets to repo
.envfiles. aspire execis for running a new command in a resource context; it is not a log reader.- If multiple AppHosts are running, pass
--apphost <path>or work from the intended AppHost folder to avoid ambiguity.
Version focus
Target the Aspire 13.2 command surface first.
aspire agent initandaspire agent mcpreplace the olderaspire mcp ...naming.aspire startis the detached-friendly shorthand;aspire run --detachremains valid.aspire docs list,aspire docs search, andaspire docs getare the preferred docs lookup commands before unfamiliar AppHost edits.list_docs,search_docs, andget_docexpose the same official docs through Aspire MCP when configured.aspire.config.jsonis the preferred rooted config file; older.aspire\settings.jsonfiles may still appear during migration.