Configuration settings

The Aspire CLI uses a configuration file to control its behavior. You can configure feature flags to enable or disable CLI features, and specify which AppHost project the CLI should use by default for an Aspire solution.

The settings file is stored in a .aspire folder and is named settings.json. Settings files can be stored locally or globally.

The following snippet is an example .aspire/settings.json file:

.aspire/settings.json

{
  "appHostPath": "../AspireShop/AspireShop.AppHost/AspireShop.AppHost.csproj",
  "features": {
    "deployCommandEnabled": "true"
  }
}

Note

For all available configuration settings in JSON format, see Example settings file.

Config file locations

A global Aspire CLI settings file is stored at $HOME/.aspire/settings.json, and is used as the default settings for the CLI. A local settings file overwrites the settings from the global file. Local settings files are stored at ./.aspire/settings.json.

Bash

You can inspect (and test existence of) the local and global settings files:

Check local and global settings files

# Check local and global settings files
for f in ./.aspire/settings.json "$HOME/.aspire/settings.json"; do
  [ -f "$f" ] && echo "$f (found)" || echo "$f (not found)"
done

# Optional: open global file
nano "$HOME/.aspire/settings.json"

PowerShell

Simple PowerShell to show file paths and whether they exist:

Check local and global settings files

$local  = "$PWD\.aspire\settings.json"
$global = "$HOME\.aspire\settings.json"
"Local :  $local  Exists: $(Test-Path $local)"
"Global:  $global Exists: $(Test-Path $global)"

# Optional: open global file in VS Code
if (Test-Path $global) { code $global }

Generating a config file

The CLI automatically generates a local settings file when you run a command that requires interaction with the AppHost, or if you set a config option. For example, aspire run searches for an AppHost project, and when found, generates the ./.aspire/settings.json file with the appHostPath setting set to the project it found.

Caution

appHostPath can be set globally, but the CLI ignores it and only reads it in the local settings file.

Settings

The Aspire CLI supports two categories of configuration settings:

• Feature flags
  These settings enable or disable specific CLI features. All feature flag setting names start with feature.

• CLI behavior
  These settings control how the CLI operates. Currently, the only CLI behavior setting is appHostPath, which specifies the location of the AppHost project.

The following table lists the settings that can be set in the config file:

Setting	Description
appHostPath	Path to default AppHost project.
features.execCommandEnabled	Enable exec command.
features.minimumSdkCheckEnabled	Enforce minimum SDK version.
features.orphanDetectionWithTimestampEnabled	Use timestamp-based orphan detection.
features.packageSearchDiskCachingEnabled	Cache package search results on disk.
features.showDeprecatedPackages	Show deprecated packages.
features.singleFileAppHostEnabled	Support single-file AppHost projects.
features.stagingChannelEnabled	Use staging channel packages.
features.updateNotificationsEnabled	Show update notifications.

Example settings file

The following is an example with all supported settings:

.aspire/settings.json

{
  "appHostPath": "../AspireShop/AspireShop.AppHost/AspireShop.AppHost.csproj",
  "features": {
    "execCommandEnabled": "true",
    "deployCommandEnabled": "true",
    "minimumSdkCheckEnabled": "true",
    "orphanDetectionWithTimestampEnabled": "true",
    "packageSearchDiskCachingEnabled": "true",
    "showDeprecatedPackages": "true",
    "singleFileAppHostEnabled": "true",
    "stagingChannelEnabled": "true",
    "updateNotificationsEnabled": "true"
  }

CLI commands

Command	Status	Function
aspire config	Stable	Command driver for managing Aspire configuration.
aspire config list	Stable	List all configuration values.
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.