Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions src/frontend/config/sidebar/reference.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -580,6 +580,32 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
slug: 'reference/cli/commands/aspire-start',
},
{ label: 'aspire stop', slug: 'reference/cli/commands/aspire-stop' },
{
label: 'aspire template',
collapsed: true,
items: [
{
label: 'aspire template',
slug: 'reference/cli/commands/aspire-template',
},
{
label: 'aspire template source',
slug: 'reference/cli/commands/aspire-template-source',
},
{
label: 'aspire template source add',
slug: 'reference/cli/commands/aspire-template-source-add',
},
{
label: 'aspire template source list',
slug: 'reference/cli/commands/aspire-template-source-list',
},
{
label: 'aspire template source remove',
slug: 'reference/cli/commands/aspire-template-source-remove',
},
],
},
{
label: 'aspire terminal',
collapsed: true,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,33 @@ The `--output` option validates the provided path before creating the project:

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.

### Select a template

When you run `aspire new` in an interactive terminal, the initial template picker lists the built-in templates together with templates from configured [template sources](#configure-template-sources). When at least one template source is configured, the picker groups its entries under nonselectable headings. Built-in templates appear under **Built-in templates**, and each configured source appears under its own heading. There's no separate submenu or search action for each source.

Each terminal entry is shown in the form `Template Name (Template Description)`. If a template has no description, only the name is shown. In the grouped terminal picker, long entries and headings are truncated with an ellipsis to fit the terminal width. When you type to search for a template, the selection moves to a matching entry rather than filtering the list. In the grouped terminal picker, search matches only the visible text of an entry.

If no template sources are configured, or if you pass `--source`, `--version`, `--channel`, or `--language`, the picker shows a flat list of the built-in templates, without headings or truncation. Those options skip the discovery of configured template sources, so templates from configured sources can't be combined with them.

<Aside type="note">
When `aspire new` runs through the Aspire extension for VS Code, the picker
is a flat list without headings. Each template from a configured source is
labeled in the form `Template Name (short-name) - source-name`.
</Aside>

#### Configure template sources

A template source is a named Git repository or local directory that contains templates. Template sources are stored in global Aspire configuration and apply to every project on the machine. Use the `aspire template source` commands to manage them rather than editing the configuration file directly:

```bash title="Aspire CLI"
aspire template source add company --repository https://github.com/example/templates
```

<LearnMore>
[Command reference: `aspire template source add`](../aspire-template-source-add/)
and [`aspire template source remove`](../aspire-template-source-remove/)
</LearnMore>

### Use \*.dev.localhost URLs?

During project creation, you may be prompted:
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
title: aspire template source add command
description: Learn about the aspire template source add command and its usage. This command adds a named template source to global configuration after confirming you trust it.
---

import Include from '@components/Include.astro';

## Name

`aspire template source add` - Add a named template source to global configuration after confirming you trust it.

## Synopsis

```bash title="Aspire CLI"
aspire template source add <name> [options]
```

## Description

The `aspire template source add` command adds a named template source to global Aspire configuration. A template source is either a Git repository (`--repository`, optionally with `--path` and `--ref`) or an absolute local directory (`--path` without `--repository`). Templates from configured sources appear in the [`aspire new`](../aspire-new/#select-a-template) template picker.

Templates can run code, so the command asks you to trust the source before it changes any configuration. After it validates the name and location, it writes the warning "Only use sources you trust. Content from these sources can run code on your machine." to standard error. Then it prompts for confirmation. The prompt shows the source name and its repository URL or local path, and defaults to **No**:

```text
Do you trust template source 'company' (https://example.com/templates)? [y/N]:
```

If you decline, the command is canceled and configuration isn't changed. To trust the source and skip the prompt, pass `--yes`.

Non-interactive invocations, including invocations where interactive input isn't available, fail unless you pass `--yes`.

## Arguments

The following arguments are available:

- **`name`**

The name of the template source. The name must be 1-64 ASCII letters, digits, dots (`.`), hyphens (`-`), or underscores (`_`), and must start with a letter or digit. Names are case-insensitive, and the command fails if a template source with the same name already exists.

## Options

The following options are available:

- **`--path`**

The template directory. Its meaning depends on whether `--repository` is specified:

- Without `--repository`, `--path` must be an absolute local directory that contains templates.
- With `--repository`, `--path` is a directory relative to the repository root. It can't be an absolute path or use `..` to point outside the repository. It defaults to the repository root (`.`).

- **`--repository`**

An HTTPS or SSH Git repository URL that contains templates.

- **`--ref`**

A Git branch, tag, or full commit SHA. Requires `--repository` and defaults to `HEAD`.

- **`-y, --yes`**

Trust the template source and skip confirmation.

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

- Add a template source and confirm trust interactively:

```bash title="Aspire CLI"
aspire template source add company --repository https://example.com/templates
```

- Add a template source from a subdirectory of a repository at a specific tag:

```bash title="Aspire CLI"
aspire template source add company --repository https://example.com/templates --path templates/web --ref v1.0.0
```

- Add a template source from an absolute local directory:

```bash title="Aspire CLI"
aspire template source add local --path /home/user/templates
```

- Add a template source in automation by explicitly trusting it:

```bash title="Aspire CLI"
aspire template source add company --repository https://example.com/templates --non-interactive --yes
```

## See also

- [aspire template source list command](../aspire-template-source-list/)
- [aspire template source remove command](../aspire-template-source-remove/)
- [aspire new command](../aspire-new/)
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
title: aspire template source list command
description: Learn about the aspire template source list command and its usage. This command lists the named template sources in global Aspire configuration.
---

import Include from '@components/Include.astro';

## Name

`aspire template source list` - List named template sources without discovering templates.

## Synopsis

```bash title="Aspire CLI"
aspire template source list [options]
```

## Description

The `aspire template source list` command lists the template sources in global Aspire configuration, sorted by name. It reads only configuration: it doesn't contact repositories or discover templates. Incomplete source definitions are included so that you can inspect and fix them.

By default, the command shows a table with each source name and its configured fields. If no sources are configured, the command says so and suggests [`aspire template source add`](../aspire-template-source-add/).

## Options

The following options are available:

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

The output format. The default is `Table`. `Json` writes an object keyed by source name to standard output, preserving the configured fields without adding defaults.

- <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 template sources as a table:

```bash title="Aspire CLI"
aspire template source list
```

- List template sources as JSON:

```bash title="Aspire CLI"
aspire template source list --format Json
```

## See also

- [aspire template source add command](../aspire-template-source-add/)
- [aspire template source remove command](../aspire-template-source-remove/)
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
title: aspire template source remove command
description: Learn about the aspire template source remove command and its usage. This command removes a named template source from global Aspire configuration.
---

import Include from '@components/Include.astro';

## Name

`aspire template source remove` - Remove a named template source from global configuration.

## Synopsis

```bash title="Aspire CLI"
aspire template source remove <name> [options]
```

## Description

The `aspire template source remove` command removes a named template source from global Aspire configuration. Templates from the removed source no longer appear in the [`aspire new`](../aspire-new/#select-a-template) template picker. The command fails if no template source with the given name exists.

## Arguments

The following arguments are available:

- **`name`**

The name of the template source to remove. Names are case-insensitive.

## Options

The following options are available:

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

- Remove a template source:

```bash title="Aspire CLI"
aspire template source remove company
```

## See also

- [aspire template source add command](../aspire-template-source-add/)
- [aspire template source list command](../aspire-template-source-list/)
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
title: aspire template source command
description: Learn about the aspire template source command and its usage. This command group manages global template sources that aspire new uses to discover templates.
---

import Include from '@components/Include.astro';

## Name

`aspire template source` - Manage global template sources.

## Synopsis

```bash title="Aspire CLI"
aspire template source [command] [options]
```

## Description

The `aspire template source` command manages global template sources. A template source is a named location that contains templates: either a Git repository or an absolute local directory. Sources are stored in the global Aspire configuration, so they apply to every project on the machine.

When at least one source is configured, the interactive [`aspire new`](../aspire-new/#select-a-template) template picker lists templates from each source alongside the built-in templates. If a configured source can't be read when `aspire new` discovers templates, the command warns about that source and continues with the others.

Template sources require the `aspire.config.json` configuration format. If your global configuration still uses the legacy format, these commands fail and direct you to run `aspire config info` to migrate it.

## Options

The following options are available:

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

## Commands

The following commands are available:

| Command | Function |
| ------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`aspire template source add <name>`](../aspire-template-source-add/) | Add a named template source after confirming you trust it. |
| [`aspire template source list`](../aspire-template-source-list/) | List the configured template sources. |
| [`aspire template source remove <name>`](../aspire-template-source-remove/) | Remove a named template source. |

## Examples

- Add a template source from a Git repository:

```bash title="Aspire CLI"
aspire template source add company --repository https://github.com/example/templates
```

- List the configured template sources:

```bash title="Aspire CLI"
aspire template source list
```

- Remove a template source:

```bash title="Aspire CLI"
aspire template source remove company
```

## See also

- [aspire new command](../aspire-new/)
- [aspire template command](../aspire-template/)
Loading
Loading