aspire agent init command

Name

aspire agent init - Initialize AI agent configuration for detected agent environments.

Synopsis

Aspire CLI

aspire agent init [options]

Description

The aspire agent init command initializes Aspire skills, companion tools, and MCP (Model Context Protocol) server configuration for your development environment. It presents an interactive multi-step flow to configure AI coding agent support:

1. Select skill locations — choose where skill files are installed (Standard .agents/skills/, Claude Code .claude/skills/, GitHub Skills .github/skills/, OpenCode .opencode/skill/). The Standard location is the only option that defaults as pre-selected.
2. Select skills and tools — choose which Aspire workflow skills and companion tools to install. The Aspire workflow skills come from the Aspire skills bundle; optional companion tools such as playwright-cli and dotnet-inspect can be selected explicitly.
3. Apply selections — installs the chosen skills into each selected location and sets up the MCP server connection.

The command also removes skill files from any locations that were deselected, keeping your workspace clean.

Aspire workflow skills bundle

Aspire workflow skills are distributed through the microsoft/aspire-skills GitHub release assets. Aspire 13.4 includes an embedded snapshot for default installs, and the optional remote fetch path can download matching release assets. The CLI verifies bundle integrity before installing selected files. The playwright-cli and dotnet-inspect companion options aren’t part of that bundle and are installed separately when selected.

Skills catalog and defaults

The Aspire skills bundle includes six workflow skills: aspire, aspire-init, aspire-orchestration, aspire-monitoring, aspire-deployment, and aspireify. The CLI reads the bundle catalog, so bundle-provided skills are available in the interactive prompt and through --skills by name.

Standalone aspire agent init pre-selects the bundle skills that are safe to add to an existing workspace: aspire, aspire-init, aspire-orchestration, aspire-monitoring, and aspire-deployment. The aspireify skill remains available but opt-in because it’s a one-time AppHost wiring workflow. When aspire init chains into agent setup, aspireify is pre-selected because it is the natural follow-up after adding an AppHost skeleton to an existing repository.

Remote bundle fetching is off by default in Aspire 13.4. To opt into downloading matching Aspire skills releases from GitHub, enable the preview feature:

Aspire CLI

aspire config set features.aspireSkillsRemoteFetchEnabled true

Installation summary

When one or more skill files are installed or updated, the command prints a single compact summary instead of one message per skill. For example, a standalone install of the default Aspire workflow skills into the standard workspace and user-level locations reports:

Output

🤖 Installed Aspire agent skills:
  Skills: aspire, aspire-deployment, aspire-init, aspire-monitoring, aspire-orchestration
  Locations: .agents/skills, ~/.agents/skills
✅ Agent environment configuration complete.

If a skill install fails, the error message includes the exact skill path that failed. No-op runs, where every selected skill is already up to date, skip the skills and locations summary and print only the final completion message.

If bundle validation fails before skill installation, see Troubleshoot skill bundle errors.

Options

The following options are available:

• --workspace-root <workspace-root>

  Path to the workspace root directory. When not specified, the current directory is used as the workspace root.

• --skill-locations <skill-locations>

  Comma-separated list of skill locations to configure, such as standard, claudecode, github, or opencode. Use all to configure all supported locations or none to skip skill location configuration. When not specified, the command prompts interactively.

• --skills <skills>

  Comma-separated list of skills to install. Aspire 13.4 includes the Aspire workflow skills aspire, aspire-init, aspire-orchestration, aspire-monitoring, aspire-deployment, and aspireify; companion options can include playwright-cli and, for .NET AppHosts, dotnet-inspect. The available list can vary by Aspire CLI version and project type. Use all to install all available skills or none to skip skill installation. When not specified, the command prompts interactively.

• -?, -h, --help

  Prints help and usage documentation for the available commands and options.

• -l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

• --non-interactive

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

• --nologo

  Suppress the startup banner and telemetry notice.

• --banner

  Display the animated Aspire CLI welcome banner.

• --wait-for-debugger

  Wait for a debugger to attach before running a command.

Examples

• Initialize AI agent configuration for detected agent environments:

  Aspire CLI

  aspire agent init

• Install all Aspire workflow skills from the Aspire skills bundle in the standard location:

  Aspire CLI

  aspire agent init --skill-locations standard --skills aspire,aspire-init,aspire-orchestration,aspire-monitoring,aspire-deployment,aspireify

• Install all available skills and companion options in all supported skill locations:

  Aspire CLI

  aspire agent init --skills all --skill-locations all

• Initialize agent configuration from a specific workspace root:

  Aspire CLI

  aspire agent init --workspace-root ./src

See also

• aspire agent command
• aspire agent mcp command