aspire new command

Name

aspire new - Create a new Aspire project or solution.

Synopsis

Aspire CLI

aspire new [command] [options]

Description

The aspire new command is the driver for creating Aspire projects, apps, or solutions, based on the Aspire templates. Each command specifies the template to use, and the options for the driver specify the options for the template.

This command defaults to interactive mode. When executed without any options, the command prompts you for the project template and version, name, and output folder. When the --name, --output, and --version options are provided, the command runs non-interactive and generates files based on the command template.

Nota

The aspire new command currently requires an interactive terminal even when all options are provided. The --non-interactive flag is not fully supported. In CI/CD pipelines or other non-interactive environments, use dotnet new with Aspire templates as an alternative for project creation.

Interactive prompts

When running aspire new in interactive mode, the command asks one or more questions before generating the project. The available prompts depend on the template and options you provide.

Use *.dev.localhost URLs?

During project creation, you may be prompted:

Use *.dev.localhost URLs?

This prompt determines whether the generated launch profile configures your Aspire services to be accessible via *.dev.localhost wildcard subdomain URLs (for example, https://myservice.dev.localhost) instead of standard http://localhost with port numbers.

What are *.dev.localhost URLs?

*.dev.localhost is a wildcard subdomain pattern that resolves to your local machine (127.0.0.1 or ::1) in most modern browsers without additional DNS configuration. This resolution is a browser feature — non-browser HTTP clients (for example, curl, HttpClient, or other command-line tools) don’t automatically resolve *.dev.localhost subdomains and may require hosts file entries to reach them.

The Aspire developer certificate trusts *.dev.localhost subdomains, so browsers accept HTTPS connections to any subdomain when the certificate is trusted.

Yes — use *.dev.localhost URLs

Choosing Yes configures the generated project so that each service gets a unique subdomain URL such as https://myservice.dev.localhost. This option:

• Enables HTTPS for all services from the start, leveraging the Aspire developer certificate.
• Gives each service its own origin, which prevents cookie and authentication token collisions between services running on the same machine.
• More closely mirrors a production setup where services are hosted on separate domains or subdomains.

Prerequisite: The Aspire developer certificate must be trusted on your machine. If you haven’t already done so, run:

Aspire CLI

aspire certs trust

Command reference: aspire certs trust

Nota

Safari on macOS does not resolve *.dev.localhost subdomains to 127.0.0.1 by default. If you use Safari, choose No or add entries to your hosts file (for example, 127.0.0.1 myservice.dev.localhost).

No — use standard localhost URLs (default)

Choosing No (the default) configures services with standard http://localhost:<port> addresses. This option requires no certificate setup and works in all browsers and tools without additional configuration.

Options

The following options are available:

• -n, --name

  The name of the project to create.

• -o, --output

  The output path for the project.

• -s, --source

  The NuGet source to use for the project templates.

• -v, --version

  The version of the project templates to use.

• --channel

  Channel to use for templates (stable, staging, daily).

• -?, -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.

Commands

Each command represents a template. Pass the --help parameter to the template command to print the options available to the template.

Command	Template
aspire-starter	Starter App (ASP.NET Core/Blazor)
aspire-ts-cs-starter	Starter App (ASP.NET Core/React)
aspire-py-starter	Starter App (FastAPI/React)
aspire-ts-starter	Starter App (Express/React)
aspire-empty	Empty (C# AppHost)
aspire-ts-empty	Empty (TypeScript AppHost)

Examples

• Create an Aspire solution from the template. Because the template was selected (aspire-starter), you’re prompted for the name, output folder, and template version.

  Aspire CLI

  aspire new aspire-starter

• Create an AppHost project named aspireapp from the 13.2.0 templates and place the output in a folder named dev.

  Aspire CLI

  aspire new aspire-empty --version 13.2.0 --name aspireapp --output ./dev

• Create an Aspire starter app using templates from the daily channel to get the latest pre-release templates.

  Aspire CLI

  aspire new aspire-starter --channel daily