App Commands

Use this when the task is about app-level lifecycle, bootstrap, or AppHost-wide maintenance.

Start The App Safely In The Background

aspire start
aspire start --isolated
aspire stop

• Use aspire start for normal background AppHost execution.
• In git worktrees or when another local instance may already be running, use aspire start --isolated.
• To restart after AppHost changes, rerun the same start command.
• Use aspire stop when cleanup is explicitly requested, ports/locks need to be released, or you are finished with a started instance that the user did not ask to keep running.
• Avoid aspire run in agent workflows — it blocks the terminal.

aspire run vs aspire start

Create A New Aspire App Or Add Aspire To An Existing App

aspire new
aspire init
aspire init --language typescript

• Use aspire new when creating a brand-new Aspire app from scratch.
• Use aspire init when adding Aspire to an existing application.

After aspire init — Hand Off to aspireify

aspire init drops a minimal AppHost skeleton + AppHost configuration into the repo and installs the aspireify agent skill alongside it. aspire init itself does not wire resources, projects, or integrations. Hand off the wiring step to:

1. The in-plugin sibling skill: ../../aspireify/SKILL.md, or
2. The project-local .agents/skills/aspireify/SKILL.md if aspire init installed it

(project-local wins — defer to it and warn the user).

The aspireify workflow:

1. Scan the repository — discover .NET projects, Node.js apps, Python/Go services, docker-compose files
2. Present findings — confirm with user which services to include
3. Wire the AppHost — add resources using 3-tier API preference:
4. Tier 1: First-party Aspire.Hosting.* (e.g., AddPostgres, AddRedis, AddViteApp, AddNextJsApp)
5. Tier 2: Community Toolkit CommunityToolkit.Aspire.Hosting.* (e.g., AddGolangApp)
6. Tier 3: Raw fallbacks (AddExecutable, AddDockerfile, AddContainer)
7. Configure dependencies — ServiceDefaults for .NET, OTel for non-.NET
8. Validate — aspire start until all resources are healthy

Key Init Rules

• Never install the obsolete Aspire workload (dotnet workload install aspire)
• Never change the repo's .NET SDK version (don't modify root global.json)
• Never change existing project target frameworks (older TFMs work with newer AppHost)
• Always use aspire docs search before writing AppHost code — don't guess APIs
• Never hardcode URLs — use endpoint references (WithReference, WithEnvironment with expressions)
• Never overwrite existing files — augment and merge
• Adapt the AppHost to the app, not the other way around

Init Config: aspire.config.json

Read aspire.config.json at repo root for init context:

C# has two sub-modes:

• Single-file: appHost.path → apphost.cs (uses #:sdk directive)
• Full project: appHost.path → directory with .csproj + Program.cs

Find The Right AppHost Or Refresh AppHost-Wide Support

aspire ps
aspire integration list --format Json
aspire integration search <query> --format Json
aspire add <package>
aspire update --self        # upgrades the Aspire CLI itself (NativeAOT global tool or curl install)
aspire update               # updates project package references / aspire.config.json
aspire restore

• Use aspire ps first to discover which AppHost is already running.
• Use aspire integration list --format Json and aspire integration search <query> --format Json for read-only integration discovery.
• Use aspire add <package> to add integrations and regenerate AppHost APIs when you are ready to mutate the AppHost.
• Use aspire update --self to upgrade the Aspire CLI itself — the safe, no-side-effect upgrade path agents can run unattended.
• Use aspire update (no --self) to refresh AppHost package references and bump pinned versions in aspire.config.json. This modifies project files — get user approval before running unattended (CI / agent flows).
• Use aspire restore after pulls, cleans, or missing generated files.
• Use --apphost <path> when the workspace has multiple AppHosts. The CLI's global config validates configured AppHost paths to catch typos early.

Key Rules

• Never install the obsolete Aspire workload (dotnet workload install aspire). Use aspire add, aspire init, or aspire new instead.
• Never edit .aspire/modules/ directly in TypeScript AppHosts. Use aspire add <package> to regenerate APIs, aspire restore if files are missing.
• For unfamiliar C# AppHost APIs, use aspire docs search as primary reference. If the dotnet-inspect skill is available, use it to inspect local symbols and overloads — but keep docs as the source of truth.
• For custom dashboard or resource commands (WithCommand), always run aspire docs search "custom resource commands" before implementing.

Look Up API Reference Before Editing AppHost Code

aspire docs search <query>
aspire docs get <slug>
aspire docs api search <query> --language csharp
aspire docs api search <query> --language typescript
aspire docs api list <scope>
aspire docs api get <id>

• Use aspire docs search and aspire docs get for workflow guidance and documented patterns.
• Use aspire docs api search when you need the C# or TypeScript API reference entry for a resource builder, extension method, or member.
• Use aspire docs api list <scope> to browse children under a language, package, module, type, or symbol.
• Always specify --language csharp or --language typescript to get the correct API surface.