Configuration settings

Aspire configuration is a rooted aspire.config.json file for project-scoped CLI configuration. Use the aspire config command family to inspect and update those settings, and use aspire config list --all to see the feature flags surfaced by your installed CLI.

Configuration file model

Starting in Aspire 13.2, Aspire prefers a rooted aspire.config.json file for project-scoped configuration. The CLI can also read and write user-scoped global defaults.

• Project-scoped configuration

  Project-scoped settings live in a rooted aspire.config.json file. This replaces the older .aspire/settings.json model.

• Global configuration

  User-scoped defaults can be set with aspire config set --global .... Project-scoped settings override global values when both are present.

The consolidated aspire.config.json file can also contain other rooted Aspire configuration such as SDK version, launch profiles, and package pins. This page focuses on the settings surfaced through aspire config.

Example aspire.config.json

aspire.config.json

{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.ts"
  },
  "channel": "staging",
  "features": {
    "defaultWatchEnabled": true,
    "showAllTemplates": true,
    "updateNotificationsEnabled": true
  }
}

The highlighted $schema property is additive

By default, the configuration files do not include the $schema property. You can add it manually to enable editor support for JSON Schema.

JSON Schema support

Aspire publishes a JSON Schema for aspire.config.json so editors can provide completions, validation, and hover documentation while you edit the file.

Two URLs are available:

• Latest — always points to the newest published schema:

  Latest schema URL

  https://aspire.dev/reference/cli/configuration/schema.json

  schema.json

• Versioned — pins to a specific Aspire release (for example, 13.2.3):

  Versioned schema URL

  https://aspire.dev/reference/cli/configuration/schema/13.2.3.json

  schema/13.2.3.json

Reference the schema from aspire.config.json

Most editors automatically pick up a schema when the JSON file declares a top-level $schema property:

aspire.config.json

{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.ts"
  }
}

Note

Use the versioned URL (for example, .../schema/13.2.3.json) when you want schema behavior to stay stable alongside a pinned Aspire CLI version, and use the unversioned schema.json when you want to always validate against the latest release.

Associate the schema in Visual Studio Code

If you prefer not to commit a $schema property, you can associate the schema with aspire.config.json in your user or workspace settings.json:

.vscode/settings.json

{
  "json.schemas": [
    {
      "fileMatch": ["aspire.config.json"],
      "url": "https://aspire.dev/reference/cli/configuration/schema.json"
    }
  ]
}

VS Code also honors the $schema property automatically, so either approach enables completions and validation in the built-in JSON language service.

Other editors

Any editor or tool that understands JSON Schema Draft 2020-12 can consume the hosted schema — including JetBrains IDEs (Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings), Neovim with jsonls, and command-line validators such as ajv or check-jsonschema. Point the tool at either the latest or versioned URL above.

Settings surfaced by aspire config

Use aspire config list to see the values that are currently set, and use aspire config list --all to enumerate the feature flags your installed CLI can configure.

Logical key	Stored in aspire.config.json as	Description
appHostPath	appHost.path	Path to the default AppHost project for the rooted configuration.
channel	channel	Default Aspire channel used by channel-aware commands such as aspire new, aspire init, and aspire update.
features.defaultWatchEnabled	features.defaultWatchEnabled	Enable or disable watch mode by default when running Aspire applications for automatic restarts on file changes.
features.execCommandEnabled	features.execCommandEnabled	Enable or disable the legacy aspire exec command for executing commands inside running resources.
features.experimentalPolyglot:go	features.experimentalPolyglot:go	Enable or disable experimental Go language support for polyglot Aspire applications.
features.experimentalPolyglot:java	features.experimentalPolyglot:java	Enable or disable experimental Java language support for polyglot Aspire applications.
features.experimentalPolyglot:python	features.experimentalPolyglot:python	Enable or disable experimental Python language support for polyglot Aspire applications.
features.experimentalPolyglot:rust	features.experimentalPolyglot:rust	Enable or disable experimental Rust language support for polyglot Aspire applications.
features.showAllTemplates	features.showAllTemplates	Show all available templates, including experimental ones, in aspire new and aspire init.
features.showDeprecatedPackages	features.showDeprecatedPackages	Show or hide deprecated packages in aspire add search results.
features.updateNotificationsEnabled	features.updateNotificationsEnabled	Enable or disable Aspire CLI update notifications.

Tip

Some feature flags shown by aspire config list --all may correspond to preview, migration, or hidden functionality. Treat the output of your installed CLI as the authoritative source for what can be configured.

Toggle preview feature experiences

Use feature flags to opt in to preview experiences that your installed Aspire CLI supports.

1. Run aspire config list --all to discover available features.* keys.

2. Enable a feature flag for the current project with aspire config set:

   Enable a project-scoped preview feature

   aspire config set features.<featureKey> true

3. Use --global (or -g) when you want the feature enabled by default across projects. Copy the key name exactly from aspire config list --all because some language-specific flags use a :<language> suffix:

   Enable a user-scoped preview feature default

   aspire config set features.<featureKey> true --global

   For example, consider the following that enables global support for Go:

   Enable global polyglot Go support

   aspire config set features:experimentalPolyglot:go true

4. Turn a feature off by setting it to false, or remove the override with aspire config delete <key>.

Working with configuration

• Use aspire config list to show currently set project-scoped and global values.

• Use aspire config list --all to include the feature flags that your installed CLI can configure.

• Use aspire config get <key> to inspect a specific setting such as channel or appHostPath.

• Use aspire config set <key> <value> to update a setting, and aspire config set --global ... when you want a user-scoped default.

CLI commands

Command	Status	Function
aspire config	Stable	Command driver for managing Aspire configuration.
aspire config list	Stable	List currently configured values, or all available feature flags with --all.
aspire config get <key>	Stable	Get a configuration value.
aspire config set <key> <value>	Stable	Set a configuration value.
aspire config delete <key>	Stable	Delete a configuration value.

For command-level details, see the aspire config command reference.