aspire

name

aspire

description

Use when working with an Aspire distributed application: operate an AppHost or resources through the Aspire CLI; start, stop, restart, or wait for resources; inspect app state, logs, traces, docs, or health; add integrations; manage secrets/config; publish/deploy or run pipeline steps; initialize an existing app; recover TypeScript `.modules`; find frontend URLs for Playwright; expose custom dashboard/resource commands; or understand Aspire AppHost APIs in C# or TypeScript. Use even if the user says AppHost, resources, dashboard, bootstrap, Playwright URL, or local distributed app workflow without naming Aspire. Do not use for non-Aspire .NET apps, container-only repos without an AppHost, or ordinary build/test tasks.

Aspire Skill

Use this skill when the task is about operating an Aspire distributed application through the Aspire CLI rather than falling back to ad-hoc dotnet, docker, or shell workflows.

Resources are typically defined in an AppHost such as, AppHost.cs, apphost.ts, or AppHost/AppHost.csproj (Program.cs).

Use this skill for

• Starting, restarting, and stopping AppHosts with aspire start and aspire stop
• Working through code changes with the right AppHost, resource, default watch, runtime hot reload, or IDE-managed workflow
• Initializing Aspire in an existing app with aspire init (drops skeleton files; use the aspireify skill to complete wiring)
• Inspecting resources, logs, traces, and docs
• Discovering integrations with aspire integration list or aspire integration search, and adding them with aspire add
• Recovering missing TypeScript AppHost support files with aspire restore
• Discovering the correct frontend URL before a Playwright handoff
• Understanding unfamiliar Aspire AppHost APIs before editing C# or TypeScript AppHosts
• Managing AppHost secrets and CLI config
• Publishing and deploying Aspire apps, including single named steps with aspire do
• Adding custom dashboard or resource commands with docs-backed AppHost patterns

Do not use this skill for

• Non-Aspire .NET applications
• Container-only workflows that do not involve an Aspire AppHost
• Replacing normal build and test commands when the task is just compiling code or running unit tests

Default workflow

1. Confirm that the workspace is an Aspire app and identify the AppHost.
2. Start the app with aspire start. Use --isolated in git worktrees or whenever shared local state would be risky.
3. Use aspire wait <resource> before interacting with a resource that needs to be healthy.
4. Inspect state with aspire describe, then use aspire otel logs, aspire logs, aspire otel traces, and aspire export before making code changes. Display returned data using the formatting rules in references/monitoring.md.
5. Before adding an integration, use aspire integration search <query> when the package is unknown, then use aspire docs search <topic> and aspire docs get <slug> for workflow guidance. Before introducing a custom dashboard/resource command or using an unfamiliar AppHost API, use docs search/get and then aspire docs api search <query> --language csharp|typescript and aspire docs api get <id> when you need the API reference entry itself.
6. When code changes, decide whether the AppHost model changed or only one resource changed. Re-run aspire start after AppHost changes; in git worktrees, re-run aspire start --isolated instead of switching to aspire run. Keep the AppHost running for resource-specific changes and use resource commands, runtime hot reload/watch, dashboard actions, or IDE-managed debugging as appropriate.

C# AppHosts

When the AppHost is implemented in C# such as AppHost.cs, apphost.cs, or a Program.cs-based AppHost, use Aspire docs for workflow guidance and Aspire API docs for the reference entry before editing.

• Use aspire docs search <topic> and aspire docs get <slug> when you need the documented workflow or pattern.
• Use aspire docs api search <query> --language csharp and aspire docs api get <id> when you need the C# API reference entry for a resource builder, extension method, or member.
• If the dotnet-inspect skill is available, use it to inspect local C# APIs, overloads, and builder chains when you need help understanding how the API surface is exposed in code.
• Keep dotnet-inspect scoped to understanding APIs and symbols; use Aspire docs for the documented workflow and recommended pattern.

TypeScript AppHosts

When the AppHost is apphost.ts, the .modules/ folder at the project root contains generated TypeScript modules that expose the Aspire APIs available to the AppHost. Common files include .modules/aspire.ts, base.ts, and transport.ts.

• Do not edit .modules/ directly.
• Use aspire integration search <query> to find the integration package, then use aspire add <package> to add integrations and regenerate the available APIs.
• Inspect .modules/aspire.ts after aspire add to see the refreshed API surface.
• The local tsconfig.json often includes .modules/**/*.ts in its compilation scope.

Key rules

• Prefer aspire start over dotnet run for AppHosts. aspire run blocks the terminal and is a poor fit for agent workflows.
• Re-running aspire start is the restart path. In git worktrees, aspire start --isolated is both the start and restart command. Do not combine aspire stop and aspire run.
• Do not stop or restart the whole AppHost just because one resource changed. Keep the AppHost running and operate on the resource directly unless the AppHost model or AppHost code changed.
• Use the command shape aspire resource <resource-name> <command> for resource operations, such as aspire resource api stop, aspire resource api start, or aspire resource api rebuild when a C# project resource exposes rebuild.
• Use features.defaultWatchEnabled only for Aspire default watch. It runs supported C# and TypeScript AppHosts in CLI watch mode for the AppHost-managed application; do not treat it as per-resource rebuild, restart, or hot reload for resource source changes.
• When the resource has its own framework/runtime hot reload, hot module replacement (HMR), or watch workflow, prefer that resource-specific workflow. Some frontend frameworks such as Vite, Next.js, and similar client-side JavaScript frameworks enable HMR by default; do not force an Aspire resource or AppHost restart when that workflow is already handling the change. IDE-managed debugging and hot reload in VS Code, Visual Studio, or Rider is delegated to the IDE and should not be mixed with Aspire CLI restart, rebuild, or watch behavior.
• Use --apphost <path> when the workspace has multiple AppHosts or discovery is ambiguous.
• Use --format Json when another tool or script needs machine-readable output.
• Use aspire integration list --format Json for read-only, scriptable integration listing. Use aspire integration search <query> --format Json for read-only, scriptable integration filtering. Use aspire add <package> only when you are ready to mutate the AppHost.
• Do not guess the integration or command shape for unfamiliar AppHost changes. Use aspire docs search and aspire docs get for the documented pattern, then use aspire docs api search and aspire docs api get when you need the specific reference entry.
• For unfamiliar C# AppHost APIs, use Aspire API docs as the primary reference and, if available, use only to inspect local symbols, overloads, and builder chains.

Common capabilities

• Use aspire ps when you need to discover running AppHosts before targeting one.
• Use aspire integration list when you need to discover available hosting integrations, or aspire integration search <query> to filter by a friendly name before adding one.
• Use aspire update when the task is to refresh AppHost package references through the supported CLI workflow.
• Use aspire doctor as an early diagnostics step when the local Aspire environment looks unhealthy.
• Use aspire resource, aspire secret, aspire config, aspire publish, aspire deploy, and aspire do when the objective is resource operations, secrets/config management, or deployment.
• Use aspire restore, aspire cache clear, aspire certs trust, and aspire certs clean when the task is local environment maintenance or recovery.

Playwright CLI

If Playwright CLI is already configured in the environment, use Aspire first to discover the running app and its endpoints, especially when multiple frontends exist. Prefer aspire describe --format Json when the handoff needs to be scriptable or you need to disambiguate which frontend URL Playwright should use, then hand browser testing off to Playwright CLI.

References

• For app-level lifecycle, bootstrap, and AppHost-wide commands, see references/app-commands.md.
• For waiting on and operating on individual resources, see references/resource-management.md.
• For app state, logs, traces, and export workflows, see references/monitoring.md.
• For deployment and pipeline-step workflows, see references/deployment.md.
• For docs, secrets, config, diagnostics, cache, and certificates, see references/tools-and-configuration.md.
• For C# AppHost API-understanding guidance, see references/csharp-apphosts.md.
• For TypeScript AppHost guidance, see references/typescript-apphosts.md.
• For Playwright handoff after Aspire endpoint discovery, see references/playwright-handoff.md.
• For investigation order and common agent workflows, see references/agent-workflows.md.