/aspire

name: aspire
description: "Orchestrates Aspire distributed applications using the Aspire CLI for running, debugging, and managing distributed apps. USE FOR: aspire start, aspire stop, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire logs, add aspire resource, aspire dashboard, update aspire apphost. DO NOT USE FOR: non-Aspire .NET apps (use dotnet CLI), container-only deployments (use docker/podman), Azure deployment after local testing (use azure-deploy skill). INVOKES: Aspire CLI commands (aspire start, aspire describe, aspire otel logs, aspire docs search, aspire add), bash. FOR SINGLE OPERATIONS: Use Aspire CLI commands directly for quick resource status or doc lookups."

Aspire Skill

This repository uses Aspire to orchestrate its distributed application. Resources are defined in the AppHost project (`apphost.cs` or `apphost.ts`).

CLI command reference

| Task | Command | |---|---| | Start the app | `aspire start` | | Start isolated (worktrees) | `aspire start --isolated` | | Restart the app | `aspire start` (stops previous automatically) | | Wait for resource healthy | `aspire wait <resource>` | | Stop the app | `aspire stop` | | List resources | `aspire describe` or `aspire resources` | | Run resource command | `aspire resource <resource> <command>` | | Start/stop/restart resource | `aspire resource <resource> start|stop|restart` | | Rebuild a .NET project resource | `aspire resource <resource> rebuild` | | View console logs | `aspire logs [resource]` | | View structured logs | `aspire otel logs [resource]` | | View traces | `aspire otel traces [resource]` | | Logs for a trace | `aspire otel logs --trace-id <id>` | | Add an integration | `aspire add` | | List running AppHosts | `aspire ps` | | Update AppHost packages | `aspire update` | | Search docs | `aspire docs search <query>` | | Get doc page | `aspire docs get <slug>` | | List doc pages | `aspire docs list` | | Environment diagnostics | `aspire doctor` | | List resource MCP tools | `aspire mcp tools` | | Call resource MCP tool | `aspire mcp call <resource> <tool> --input <json>` |

Most commands support `--format Json` for machine-readable output. Use `--apphost <path>` to target a specific AppHost.

Key workflows

Running in agent environments

Use `aspire start` to run the AppHost in the background. When working in a git worktree, use `--isolated` to avoid port conflicts and to prevent sharing user secrets or other local state with other running instances:

aspire start --isolated

Use `aspire wait <resource>` to block until a resource is healthy before interacting with it:

aspire start --isolated
aspire wait myapi

Applying code changes

Choose the right action based on what changed:

| What changed | Action | Why | |---|---|---| | AppHost project (`apphost.cs`/`apphost.ts`) | `aspire start` | Resource graph changed; full restart required | | Compiled .NET project resource | `aspire resource <name> rebuild` | Rebuilds and restarts only that resource | | Interpreted resource (JavaScript, Python) | Typically nothing — most run with file watchers | Restart the resource if no watch mode is configured |

**Never restart the entire AppHost just because a single resource changed.** Use `aspire resource <name> rebuild` for .NET project resources — it coordinates stop, build, and restart for just that resource. Use `aspire describe --format Json` to check which commands a resource supports.

Debugging issues

Before making code changes, inspect the app state:

1. `aspire describe` — check resource status 2. `aspire otel logs <resource>` — view structured logs 3. `aspire logs <resource>` — view console output 4. `aspire otel traces <resource>` — view distributed traces

Adding integrations

Use `aspire docs search` to find integration documentation, then `aspire docs get` to read the full guide. Use `aspire add` to add the integration package to the AppHost.

After adding an integration, restart the app with `aspire start` for the new resource to take effect.

Using resource MCP tools

Some resources expose MCP tools (e.g. `WithPostgresMcp()` adds SQL query tools). Discover and call them via CLI:

aspire mcp tools                                              # list available tools
aspire mcp tools --format Json                                # includes input schemas
aspire mcp call <resource> <tool> --input '{"key":"value"}'   # invoke a tool

Important rules

• **Always start the app first** (`aspire start`) before making changes to verify the starting state.
• **To restart, just run `aspire start` again** — it automatically stops the previous instance. NEVER use `aspire stop` then `aspire run`. NEVER use `aspire run` at all.
• **Only restart the AppHost when AppHost code changes.** For .NET project resources, use `aspire resource <name> rebuild` instead.
• Use `--isolated` when working in a worktree.
• **Avoid persistent containers** early in development to prevent state management issues.
• **Never install the Aspire workload** — it is obsolete.
• **For Aspire API reference and documentation, prefer `aspire docs search <query>` and `aspire docs get <slug>`** over searching NuGet package caches or XML doc files. The CLI provides up-to-date content from aspire.dev.
• Prefer `aspire.dev` and `learn.microsoft.com/microsoft/aspire` for official documentation.

Playwright CLI

If configured, use Playwright CLI for functional testing of resources. Get endpoints via `aspire describe`. Run `playwright-cli --help` for available commands.