From 60926708702e1a6b33056b5fc874ddfe1be0840f Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Thu, 29 Oct 2026 01:50:40 +0000 Subject: [PATCH] Document global template sources CLI --- .../config/sidebar/reference.topics.ts | 14 ++ .../reference/cli/commands/aspire-new.mdx | 6 + .../cli/commands/aspire-template-source.mdx | 147 ++++++++++++++++++ .../cli/commands/aspire-template.mdx | 48 ++++++ 4 files changed, 215 insertions(+) create mode 100644 src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx create mode 100644 src/frontend/src/content/docs/reference/cli/commands/aspire-template.mdx diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index e93e30c950..2949772ceb 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -606,6 +606,20 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = { }, ], }, + { + 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 update', slug: 'reference/cli/commands/aspire-update', diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index c557f4dcb0..c146c37cb8 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -48,6 +48,12 @@ 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. +### Search for more templates + +When you've configured one or more [global template sources](../aspire-template-source/), the template list includes a **Search for more templates** option. Enter text to match template short names, display names, and descriptions (case-insensitive), or leave it empty to list every template. Results show the source that provided each template, and you can search again or return to the built-in templates. + +Configured templates can't be combined with `--source`, `--version`, `--channel`, or `--language`. + ### Use \*.dev.localhost URLs? During project creation, you may be prompted: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx new file mode 100644 index 0000000000..7792743f54 --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx @@ -0,0 +1,147 @@ +--- +title: aspire template source command +description: Learn how to add, remove, and list global template sources with the aspire template source commands, so aspire new can discover templates from local directories and Git repositories. +--- + +import Include from '@components/Include.astro'; +import { Aside } from '@astrojs/starlight/components'; + +## Name + +`aspire template source` - Manage global template sources. + +## Synopsis + +```bash title="Aspire CLI" +aspire template source add (--path | --repository ) [--ref ] [options] +aspire template source remove [options] +aspire template source list [--format ] [options] +``` + +## Description + +A template source is a named location that contains reusable templates. A source is either a local directory or a Git repository. Sources are stored in the global Aspire configuration file (`~/.aspire/aspire.config.json`) under the `templateSources` key, and they apply to every project on the machine. + +When at least one source is configured, interactive [`aspire new`](../aspire-new/) adds a **Search for more templates** option to its template list. Searches match a template's short name, display name, and description from its `template.json` file, case-insensitively. An empty search lists every template. Results show the name of the source that provided each template. + +The `aspire template source` commands require the modern `aspire.config.json` format. If only legacy configuration exists, the commands report an error that directs you to run `aspire config info` to migrate it. + +## Commands + +| Command | Function | +| -------------------------------------------- | ------------------------------------------- | +| `aspire template source add ` | Add or update a global template source. | +| `aspire template source remove ` | Remove a global template source. | +| `aspire template source list` | List the configured global template sources. | + +### `aspire template source add` + +Adds a named source. Provide either `--path` for a local directory, or `--repository` for a Git repository. When you use `--repository`, `--path` optionally selects a subdirectory within the repository, and `--ref` selects a branch, tag, or commit. If you omit `--ref` it defaults to `HEAD`, and if you omit `--path` it defaults to `.`. + +- `` + + The name of the source. Names are compared case-insensitively and can't contain dots, colons, or control characters. + +- `--path ` + + The absolute path to a local directory that contains templates, or, with `--repository`, the subdirectory within the repository. + +- `--repository ` + + The Git repository URL. HTTPS and SSH URLs are accepted. SCP-style shorthand and URLs with embedded credentials aren't accepted. + +- `--ref ` + + The Git branch, tag, or commit to use. Applies to `--repository`. + +### `aspire template source remove` + +Removes the source with the given name from the global configuration. + +### `aspire template source list` + +Lists the configured sources without discovering templates or contacting repositories. Incomplete definitions are included. + +- `--format ` + + The output format. The default is `Table`, which shows bold column headers and a dash for empty cells. `Json` writes an object keyed by source name, sorted by name, to stdout. The output preserves the configured fields and doesn't add defaults. + +## Options + +The following options are available: + +- + +- + +- + +- + +- + +- + +## Configuration file format + +Sources are objects registered under the global `templateSources` key: + +```json title="~/.aspire/aspire.config.json" +{ + "templateSources": { + "company": { + "path": "/absolute/path/to/company-templates" + }, + "release": { + "repository": "https://github.com/microsoft/aspire-templates", + "ref": "release/17.0", + "path": "templates" + } + } +} +``` + +Project-level `templateSources` settings aren't used. Unknown fields are ignored when the configuration is read, and edits made by these commands preserve fields they don't recognize. + +If a configured source fails discovery during `aspire new`, the command warns about that source and continues with the healthy ones. Malformed configuration fails the command instead of being skipped silently. + + + +## Examples + +- Add a local directory as a source: + + ```bash title="Aspire CLI" + aspire template source add company --path /absolute/path/to/company-templates + ``` + +- Add a Git repository as a source: + + ```bash title="Aspire CLI" + aspire template source add examples --repository https://github.com/microsoft/aspire-templates + ``` + +- Add a Git repository pinned to a ref and subdirectory: + + ```bash title="Aspire CLI" + aspire template source add release --repository https://github.com/microsoft/aspire-templates --ref release/17.0 --path templates + ``` + +- List sources as JSON: + + ```bash title="Aspire CLI" + aspire template source list --format json + ``` + +- Remove a source: + + ```bash title="Aspire CLI" + aspire template source remove examples + ``` + +## See also + +- [aspire new command](../aspire-new/) +- [aspire template command](../aspire-template/) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-template.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-template.mdx new file mode 100644 index 0000000000..404276ba08 --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-template.mdx @@ -0,0 +1,48 @@ +--- +title: aspire template command +description: Learn about the aspire template command and its usage. This command group is used to manage template configuration for the Aspire CLI. +--- + +import Include from '@components/Include.astro'; + +## Name + +`aspire template` - Manage templates. + +## Synopsis + +```bash title="Aspire CLI" +aspire template [command] [options] +``` + +## Description + +The `aspire template` command manages template configuration for the Aspire CLI. Currently, it contains the `source` command group, which manages global template sources used by [`aspire new`](../aspire-new/). + +## Options + +The following options are available: + +- + +- + +- + +- + +- + +- + +## Commands + +The following commands are available: + +| Command | Status | Function | +| ------------------------------------------------------- | ------ | ------------------------------------------------ | +| [`aspire template source`](../aspire-template-source/) | Stable | Manage global template sources. | + +## See also + +- [aspire new command](../aspire-new/)