getting-started-with-aspire

$npx mdskill add microsoft/aspire.dev/getting-started-with-aspire

[Aspire](https://aspire.dev) is a polyglot stack for building, running, debugging, and deploying distributed applications. The AppHost can be authored in C# or TypeScript today, with additional languages (Java, Go, Python, Rust, …) on the roadmap. The Aspire CLI (`aspire`) is the entry point for everything: scaffolding apps, running them locally, inspecting state, and deploying.

SKILL.md

.github/skills/getting-started-with-aspireView on GitHub ↗
---
name: getting-started-with-aspire
description: "Use this skill when a developer asks how to begin using Aspire — installing the Aspire CLI, creating a new Aspire app, running it locally, or finding the authoritative docs, integration catalog, or API reference on aspire.dev. Use it for questions like \"how do I install aspire?\", \"how do I create a new aspire app?\", \"how do I run my aspire app?\", or \"where is the documentation for aspire?\". Do not use it for operating an existing Aspire AppHost (use the official `aspire` skill at github.com/microsoft/aspire/tree/main/.agents/skills/aspire), authoring AppHost code, or adding integrations to an existing app."
---

# Getting started with Aspire

[Aspire](https://aspire.dev) is a polyglot stack for building, running, debugging, and deploying distributed applications. The AppHost can be authored in C# or TypeScript today, with additional languages (Java, Go, Python, Rust, …) on the roadmap. The Aspire CLI (`aspire`) is the entry point for everything: scaffolding apps, running them locally, inspecting state, and deploying.

## When to use this skill

- The user is new to Aspire and wants to install the CLI.
- The user wants to scaffold a brand-new Aspire app.
- The user wants to know how to run the app they just created.
- The user is looking for the authoritative docs, integration catalog, or API reference.

## Don't use this skill for

- Operating an existing Aspire AppHost (resources, logs, traces, dashboard commands). That's the [official `aspire` skill](https://github.com/microsoft/aspire/tree/main/.agents/skills/aspire).
- Editing AppHost source code (C# or TypeScript) — consult the API reference on aspire.dev.

## Install the Aspire CLI

The official cross-platform installers are hosted on aspire.dev:

- **Windows (PowerShell):** `iex (irm https://aspire.dev/install.ps1)`
- **macOS / Linux (bash):** `curl -fsSL https://aspire.dev/install.sh | bash`

After install, verify with `aspire --version`. Do not install Aspire from NuGet/npm directly when the user wants the CLI — the install script is the supported path.

## Create a new Aspire app

```sh
aspire new
```

`aspire new` is **interactive**. It prompts for the template (for example `aspire-starter`, `apphost`, `apphost-ts`), the project name, the output location, and the language. It creates a subfolder for the new project, so run it from the parent directory where you want the project folder to live. Do not pass fabricated template flags; let the CLI prompt the user.

## Run the app

```sh
cd <project>
aspire start
```

`aspire start` launches the AppHost and the Aspire dashboard. Prefer `aspire start` over `dotnet run` for AppHosts — `aspire start` is the agent-friendly path; `aspire run` blocks the terminal.

## Where to learn more

- **Documentation hub:** <https://aspire.dev/docs/>
- **CLI reference:** <https://aspire.dev/reference/cli/>
- **Integration catalog:** <https://aspire.dev/integrations/>
- **C# API reference:** <https://aspire.dev/reference/api/csharp/>
- **TypeScript API reference:** <https://aspire.dev/reference/api/typescript/>
- **LLM-friendly corpus:** <https://aspire.dev/llms.txt>, <https://aspire.dev/llms-full.txt>
- **Per-page markdown:** every page on aspire.dev is also available as `<page>.md` (or via `Accept: text/markdown` content negotiation).
- **In-page search tool:** when running in a WebMCP-capable browser, the `search-aspire-docs` tool is registered on every aspire.dev page.
- **Source repository:** <https://github.com/microsoft/aspire>

More from microsoft/aspire.dev

SkillDescription
aspireOrchestrates 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.
container-imagesExtracts all container image references (registry, image, tag) from the microsoft/aspire source code and produces a JSON data file for the aspire.dev Astro site. USE FOR: update container images JSON, refresh container image data, list all aspire container images, sync container image versions, generate container-images.json. DO NOT USE FOR: updating the container image versions in aspire source code itself (that's a product repo change), NuGet package data (use the integrations skill), or Dockerfile-based images for dev containers. INVOKES: bash, file read/write. FOR SINGLE OPERATIONS: Use grep/find to quickly check a single image tag.
doc-pr-reviewerReviews a single documentation pull request for the aspire.dev repository, verifying that every factual claim it makes about Aspire matches its source of truth — microsoft/aspire (core), CommunityToolkit/Aspire (toolkit integrations), and optionally Azure/azure-sdk-for-net (Azure provisioning APIs) — and validating the docs as a new user would via the doc-tester skill. Use when asked to review, verify, or audit a specific docs PR for accuracy.
doc-testerAgent for validating Aspire documentation against actual behavior. Use when auditing documentation accuracy, testing examples, or identifying discrepancies between documentation and implementation.
playwright-cliAutomates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
twoslash-validatorValidate and fix two-slash TypeScript examples for aspire.dev. Use when adding or editing `twoslash` code fences, TypeScript AppHost samples, generated TypeScript API data, or failures from `pnpm test:unit:twoslash-blocks`.
update-integrationsUpdate integration documentation links and API reference data by synchronizing NuGet package names with their documentation URLs and generating per-package API schemas. Use when adding new integrations, refreshing package data, ensuring integration-docs.json stays in sync with aspire-integrations.json, or regenerating API reference JSON files.
update-samplesUpdate the samples data file by fetching sample metadata from the microsoft/aspire-samples GitHub repository. Use when adding new samples, refreshing sample data, or ensuring samples.json stays in sync with the upstream repo.
whatsnewStep-argument skill that formalizes writing an Aspire \"What's new in N.N\" release-notes page (src/frontend/src/content/docs/whats-new/aspire-N-N.mdx) as a repeatable lifecycle. Invoke as `/whatsnew {modality}` where modality is one of: draft/scaffold (init), research, critique, validate, polish, review. USE FOR: start/scaffold a new what's-new page for a release, research a release's changes into a dossier and author the draft prose, critique a draft, fact-check/validate the diff, polish and run data ingestion, or sign off the PR. DO NOT USE FOR: general docs pages (use doc-writer), reviewing an arbitrary docs PR (use doc-pr-reviewer), or product-repo changes. ORCHESTRATES: doc-writer, doc-pr-reviewer, doc-tester, twoslash-validator, update-integrations, update-samples, container-images.