# aspire ls command

## Name

`aspire ls` - List AppHost project candidates.

## Synopsis

```bash title="Aspire CLI"
aspire ls [options]
```

## Description

The `aspire ls` command discovers and lists [AppHost project](/get-started/app-host/) candidates in the current working directory and its subdirectories. It performs parallel discovery and reports results along with each candidate's programming language and build status.

The default output is a human-readable table with the following columns:

| Column     | Description                                                                       |
| ---------- | --------------------------------------------------------------------------------- |
| `PATH`     | The file path to the AppHost project                                              |
| `LANGUAGE` | The raw AppHost language ID, such as `csharp` or `typescript/nodejs`              |
| `STATUS`   | Build status of the AppHost candidate: `buildable` or `possibly-unbuildable`      |

The `STATUS` value is `buildable` when the project validates as an AppHost candidate. It is `possibly-unbuildable` when the project looks like an AppHost but may not build in the current environment.

### Discovery and configuration

If a configuration file (for example `aspire.config.json` with `appHost.path` or a legacy `.aspire/settings.json` with `appHostPath`) points to an AppHost project, that path is included as a candidate. When a configured AppHost path points to a missing file, `aspire ls` displays a warning. When the configuration file is invalid JSON, has an invalid shape, or the configured AppHost path is empty, contains invalid characters, or isn't a JSON string, `aspire ls` displays an error. When no configuration file is present, discovery continues silently.

### Output ordering

**Non-streaming mode** (`--format json` without `--stream`): results are sorted by path before output.

**Streaming mode** (`--format json --stream`): results are emitted in arrival order from parallel discovery and are **not sorted**. If you need a deterministic order for streamed output, pipe through a sort step. For example:

```bash title="Aspire CLI"
aspire ls --format json --stream | jq -s 'sort_by(.path)'
```

This example uses [jq](https://jqlang.org/), a third-party JSON processor.

## Options

The following options are available:

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

  Output result format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`.

- **`--stream`**

  Output discovered AppHosts as newline-delimited JSON (NDJSON), emitting each candidate as soon as it is discovered. Requires `--format json`.

- **`--all`**

  Include all candidate AppHosts by disabling Git filtering and the built-in skip list for common dependency, build-output, and tooling directories such as `bin`, `obj`, `node_modules`, `.venv`, `.git`, and `.vs`. The NuGet package cache is still excluded.

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

- List all discovered AppHost candidates in table format:

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

  Example output:

  ```text title="Output"
  PATH                                                  LANGUAGE           STATUS
  ./src/MyApp.AppHost/MyApp.AppHost.csproj              csharp             buildable
  ./src/OtherApp.AppHost/apphost.ts                     typescript/nodejs  buildable
  ```

- Output discovered AppHosts as JSON for scripting:

  ```bash title="Aspire CLI"
  aspire ls --format json
  ```

  Example output:

  ```json title="Output"
  [
    {
      "path": "./src/MyApp.AppHost/MyApp.AppHost.csproj",
      "language": "csharp",
      "status": "buildable"
    },
    {
      "path": "./src/OtherApp.AppHost/apphost.ts",
      "language": "typescript/nodejs",
      "status": "buildable"
    }
  ]
  ```

- Stream discovered AppHosts as newline-delimited JSON:

  ```bash title="Aspire CLI"
  aspire ls --format json --stream
  ```

  Example output (each line is a JSON object emitted as candidates are discovered; your line order may vary):

  ```text title="Output"
  {"path":"./src/OtherApp.AppHost/apphost.ts","language":"typescript/nodejs","status":"buildable"}
  {"path":"./src/MyApp.AppHost/MyApp.AppHost.csproj","language":"csharp","status":"buildable"}
  ```

  Note: lines are emitted in discovery arrival order and are not sorted. To sort streamed output by path:

  ```bash title="Aspire CLI"
  aspire ls --format json --stream | jq -s 'sort_by(.path)'
  ```

- Include all AppHost candidates, ignoring `.gitignore` and directory filters:

  ```bash title="Aspire CLI"
  aspire ls --all
  ```

## See also

- [aspire run](/reference/cli/commands/aspire-run/)
- [aspire ps](/reference/cli/commands/aspire-ps/)