aspire doctor command

Name

aspire doctor - Check the Aspire development environment for common issues.

Synopsis

aspire doctor [options]

Description

The aspire doctor command runs a series of diagnostic checks to verify that your development environment is properly configured for Aspire development. It checks prerequisites such as the .NET SDK, container runtime, and environment settings.

This command is useful for troubleshooting when you encounter issues with Aspire or when setting up a new development environment. The checks are grouped by category:

SDK checks: Verifies .NET SDK installation and version requirements
Container checks: Validates container runtime (Docker and/or Podman) availability, running status, and version. Reports which runtime is active and why (explicit configuration, auto-detected default, or auto-detected only runtime running)
Environment checks: Validates environment variables and other settings, including the JavaScript toolchain required by TypeScript AppHosts (npm, pnpm, Yarn, or Bun)

The command displays results with clear status indicators:

✅ (green) - Check passed
⚠️ (yellow) - Warning (non-blocking issue)
❌ (red) - Check failed (blocking issue)

If any checks fail, the command provides suggestions for how to fix the issues and links to relevant documentation.

Options

The following options are available:

--format <Table|Json>

Output format (Table or Json). Use Json for automation scenarios or when you need to parse the results programmatically. Defaults to Table.
-?, -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

Run diagnostic checks on your development environment:
Aspire CLI
```
aspire doctor
```
Run diagnostic checks with JSON output:
Aspire CLI
```
aspire doctor --format Json
```

Sample output

When you run aspire doctor, you see output similar to the following:

Aspire Environment Check
========================

.NET SDK
✅ .NET SDK 10.0.100 or later is installed

Container Runtime
  ✅ Docker v27.3.1: running (auto-detected (default)) ← active
  ✅ Podman v5.3.0: installed (available)

Environment
✅ HTTPS development certificate is trusted

When only Podman is running:

Container Runtime
  ✅ Podman v5.3.0: running (auto-detected (only runtime running)) ← active
  ❌ Docker is not installed

When you set ASPIRE_CONTAINER_RUNTIME=podman, Aspire honors the explicit configuration and Podman becomes active even when Docker is also running:

Container Runtime
  ✅ Podman v5.3.0: running (explicit configuration) ← active
  ✅ Docker v27.3.1: running (available)

The active runtime is annotated with ← active. Other detected runtimes are shown with (available).

Exit codes

The command returns the following exit codes:

Exit code	Description
`0`	All checks passed (warnings are allowed)
`1`	One or more checks failed

JSON output format

When using the --format Json option, the output includes a structured response with all check results and a summary:

{
  "checks": [
    {
      "category": "sdk",
      "message": ".NET SDK 10.0.100 or later is installed",
      "status": "Pass"
    }
  ],
  "summary": {
    "passed": 5,
    "warnings": 0,
    "failed": 0
  }
}