aspire ls command

Name

aspire ls - List AppHost project candidates.

Synopsis

Aspire CLI

aspire ls [options]

Description

The aspire ls command discovers and lists AppHost project 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:

Aspire CLI

aspire ls --format json --stream | jq -s 'sort_by(.path)'

This example uses jq, 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.

• -?, -h, --help

  Prints help and usage documentation for the available commands and options.

• -l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

• --non-interactive

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

• --nologo

  Suppress the startup banner and telemetry notice.

• --banner

  Display the animated Aspire CLI welcome banner.

• --wait-for-debugger

  Wait for a debugger to attach before running a command.

Examples

• List all discovered AppHost candidates in table format:

  Aspire CLI

  aspire ls

  Example output:

  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:

  Aspire CLI

  aspire ls --format json

  Example output:

  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:

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

  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:

  Aspire CLI

  aspire ls --format json --stream | jq -s 'sort_by(.path)'

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

  Aspire CLI

  aspire ls --all

See also

• aspire run
• aspire ps