# aspire run command

## Name

`aspire run` - Run an Aspire AppHost in development mode.

## Synopsis

```bash title="Aspire CLI"
aspire run [options] [[--] <additional arguments>...]
```

## Description

The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the AppHost, launches the web dashboard, and prints a list of endpoints.

<Include relativePath="reference/cli/includes/project-search-logic-description.md" />

The command performs the following steps to run an Aspire AppHost:

- Creates or updates the rooted `aspire.config.json` file and records the
  selected AppHost there. Legacy `.aspire/settings.json` files are still read
  during migration.
- Installs or verifies that Aspire's local hosting certificates are installed and trusted.
- Builds the AppHost project and its resources.
- Starts the AppHost and its resources.
- Starts the dashboard.

## Stopping the AppHost

To stop the running AppHost and exit, press <Kbd windows="Ctrl+C" mac="⌃+C" linux="Ctrl+C" /> (or send `SIGTERM` on Linux/macOS). The CLI requests a graceful shutdown of the AppHost and its resources.

If graceful shutdown is taking too long and you need to exit immediately, press <Kbd windows="Ctrl+C" mac="⌃+C" linux="Ctrl+C" /> a second time to terminate the process immediately.

## Hot Reload and watch behavior

By default, `aspire run` starts the distributed application once. It doesn't watch the AppHost or resource source files. After you change AppHost code, stop the running AppHost with <Kbd windows="Ctrl+C" mac="⌃+C" linux="Ctrl+C" />, and then run `aspire run` again. For individual resource changes, keep the AppHost running and restart or rebuild the resource from the Aspire CLI or dashboard when needed.

Aspire also has an opt-in `defaultWatchEnabled` feature flag. When enabled, Aspire uses watch mode by default and automatically restarts the Aspire application after file changes:

```bash title="Aspire CLI"
aspire config set features.defaultWatchEnabled true
```

Use Aspire watch mode when you want Aspire to restart the AppHost-managed application for you after AppHost changes. It supports both C# and TypeScript AppHosts; C# project resources are also controlled by this setting today. Other resource hot reload behavior depends on the framework or runtime backing the resource. For more information, see [Hot Reload and watch](/app-host/hot-reload-and-watch/).

The following snippet is an example of the output displayed by the `aspire run` command:

```bash title="Aspire CLI"
Dashboard:  https://localhost:17244/login?t=9db79f2885dae24ee06c6ef10290b8b2

    Logs:  /home/vscode/.aspire/cli/logs/apphost-5932-2025-08-25-18-37-31.log

        Press CTRL+C to stop the apphost and exit.
```

## Options

The following options are available:

- **`--`**

  Delimits arguments to `aspire run` from arguments for the AppHost being run. All arguments after this delimiter are passed to the AppHost run.

- **`--detach`**

  Run the AppHost in the background and exit after it starts. The AppHost continues running as a background process. Use `aspire ps` to list running AppHosts and `aspire stop` to stop them.

- **`--format <Json|Table>`**

  Output result format. Only valid when used with `--detach`. Use `Json` for machine-readable output suitable for scripting and automation.

- **`--isolated`**

  Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. This is useful for parallel testing or comparing different configurations side-by-side.

- **`--no-build`**

  Do not build or restore the project before running. Use this option when you have already built the project and want to skip the build step for faster startup.

- <Include relativePath="reference/cli/includes/option-project.md" />

- <Include relativePath="reference/cli/includes/option-help.md" />

- <Include relativePath="reference/cli/includes/option-log-level.md" />

- <Include relativePath="reference/cli/includes/option-non-interactive.md" />

- <Include relativePath="reference/cli/includes/option-nologo.md" />

- <Include relativePath="reference/cli/includes/option-banner.md" />

- <Include relativePath="reference/cli/includes/option-wait.md" />

## Examples

- Search the current directory structure for AppHost projects to build and run:

  ```bash title="Aspire CLI"
  aspire run
  ```

- Run a specific AppHost project:

  ```bash title="Aspire CLI"
  aspire run --apphost './projects/apphost/orchestration.AppHost.csproj'
  ```

- Run a specific AppHost project with arguments:

  ```bash title="Aspire CLI"
  aspire run --apphost './projects/apphost/orchestration.AppHost.csproj' -- -fast
  ```

- Run the AppHost in the background:

  ```bash title="Aspire CLI"
  aspire run --detach
  ```

- Run the AppHost in the background with JSON output:

  ```bash title="Aspire CLI"
  aspire run --detach --format Json
  ```

- Run in isolated mode for parallel testing:

  ```bash title="Aspire CLI"
  aspire run --isolated
  ```

- Skip building and run immediately:

  ```bash title="Aspire CLI"
  aspire run --no-build
  ```