Registries
registry.toml
A registry is a directory that contains a registry.toml file and a templates/ subdirectory. Registries are registered with spin registry add <alias> <source>.
Layout
registry/
registry.toml
templates/
go-cli.toml
rust-api.toml
spin search and spin add <alias>/<id> read this directory. spin registry update refreshes git registries from upstream.
registry.toml
id = "official"
name = "Official Spin Templates"
description = "Curated templates maintained by the spin team."
homepage = "https://github.com/example/spin-registry"
maintainer = "Spin Team"
license = "MIT"
Fields
| Field | Required | Description |
|---|---|---|
id | yes | Machine identifier. Must match the alias used with spin registry add. |
name | yes | Human-readable registry name. |
description | no | Short summary shown in spin registry list. |
homepage | no | Registry homepage or repository URL. |
maintainer | no | Maintainer name or contact. |
license | no | Registry metadata license. |
templates/*.toml
Each template in the registry gets one TOML file in templates/. The file basename (without .toml) must match the id field.
id = "go-cli"
name = "Go CLI"
description = "Minimal Go CLI with cobra and charmbracelet/log."
source = "https://github.com/example/go-cli-template.git"
tags = ["cli", "go", "charm"]
authors = ["Sam"]
license = "MIT"
homepage = "https://github.com/example/go-cli-template"
type = "cli"
language = "go"
version = "0.2.0"
updated_at = "2026-07-09"
Fields
| Field | Required | Description |
|---|---|---|
id | yes | Short template ID. Must match the file basename. |
name | yes | Human-readable template name. |
description | no | Shown in search results. |
source | yes | Where the template lives. Can be a git URL, a local path, or another <alias>/<id> shorthand (one level of chaining allowed). |
tags | no | Search keywords. |
authors | no | Template authors. |
license | no | Template license. |
homepage | no | Template homepage. |
type | no | cli, tui, lib, etc. |
language | no | Primary language. |
version | no | Template version. |
updated_at | no | ISO 8601 date. |
Chaining
A template's source can point at another registry template using the same <alias>/<id> shorthand:
id = "go-cli-extended"
name = "Go CLI Extended"
source = "official/go-cli"
Only one level of chaining is followed. Cycles are rejected.
Validation
spin registry add refuses a source that does not contain both registry.toml and a templates/ directory. spin search skips individual template files that fail validation, but still indexes the rest of the registry.