# 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

<Include relativePath="reference/cli/includes/config-file-description.md" />

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`

```json title="aspire.config.json" {2}
{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.mts"
  },
  "channel": "staging",
  "features": {
    "defaultWatchEnabled": true,
    "showAllTemplates": true,
    "updateNotificationsEnabled": true
  }
}
```

:::tip[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:

  ```text title="Latest schema URL"
  https://aspire.dev/reference/cli/configuration/schema.json
  ```

  [`schema.json`](/reference/cli/configuration/schema.json)

- **Versioned** — pins to a specific Aspire release (for example, `13.2.3`):

  ```text title="Versioned schema URL"
  https://aspire.dev/reference/cli/configuration/schema/13.2.3.json
  ```

  [`schema/13.2.3.json`](/reference/cli/configuration/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:

```json title="aspire.config.json" ins={2}
{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.mts"
  }
}
```

:::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](/get-started/aspire-vscode-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`](https://github.com/microsoft/vscode-json-languageservice), and
command-line validators such as
[`ajv`](https://ajv.js.org/) or [`check-jsonschema`](https://github.com/python-jsonschema/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.

<Include relativePath="reference/cli/includes/config-settings-table.md" />

### Configure the AppHost path

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

```bash title="Set the local AppHost path"
aspire config set appHost.path ./apphost.mts
```

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

```json title="aspire.config.json"
{
  "appHost": {
    "path": "./apphost.mts"
  }
}
```

The AppHost path can point to the entry point used by your AppHost language, such
as `apphost.mts`, `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`:

   ```bash title="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:

   ```bash title="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:

   ```bash title="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`](/reference/cli/commands/aspire-config/)                       | Stable | Command driver for managing Aspire configuration.                              |
| [`aspire config list`](/reference/cli/commands/aspire-config-list/)             | Stable | List currently configured values, or all available feature flags with `--all`. |
| [`aspire config get <key>`](/reference/cli/commands/aspire-config-get/)         | Stable | Get a configuration value.                                                     |
| [`aspire config set <key> <value>`](/reference/cli/commands/aspire-config-set/) | Stable | Set a configuration value.                                                     |
| [`aspire config delete <key>`](/reference/cli/commands/aspire-config-delete/)   | Stable | Delete a configuration value.                                                  |

<LearnMore>
  For command-level details, see the [`aspire config` command
  reference](/reference/cli/commands/aspire-config/).
</LearnMore>