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. Project-specific values such as appHost.path must be configured locally in aspire.config.json.

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

With the Aspire VS Code extension installed, the schema is registered for aspire.config.json automatically. Without the extension, add a $schema property to the top of aspire.config.json (see above) or map the schema manually in .vscode/settings.json under json.schemas.

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
appHost.path	appHost.path	Project-scoped path to the default AppHost entry point. This setting must be configured in the local aspire.config.json file.
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.

Configure the AppHost path

Use appHost.path to set the default AppHost entry point for the current configuration root:

Set the local AppHost path

aspire config set appHost.path ./apphost.ts

The CLI writes this value to the local aspire.config.json file:

aspire.config.json

{
  "appHost": {
    "path": "./apphost.ts"
  }
}

The AppHost path can point to the entry point used by your AppHost language, such as apphost.ts, Program.cs, or an AppHost project file. The path is project-specific and can’t be configured globally. If a global settings file contains appHost.path or the legacy appHostPath key, the CLI ignores that value and warns that AppHost paths must be configured locally. The legacy appHostPath key is also blocked by aspire config set; use appHost.path instead.

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 appHost.path.

• 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.