Managing Templates

Templates are a Spin tool for scaffolding new applications and components. You can use them via the spin new and spin add commands. For more information about creating applications with templates, see Writing Spin Applications.

Installing Templates

This section covers general principles for installing templates. For information about installing templates for specific languages, see Writing Spin Applications.

To install templates, use the spin templates install command. You can install templates from a Git repository, or while authoring templates you can install them from a local directory.

Installing From the Spin Git Repository

To install templates from the Spin Git repository, run spin templates install --git:

$ spin templates install --git https://github.com/fermyon/spin

If you prefer a shorter command, you can just pass the repository id instead of the full URL:

$ spin templates install --git fermyon/spin

The above command installs all templates in the repository.

Language SDKs often ship templates in their repositories; see the relevant language guide to find out where to get its templates.

Installing From a Specific Branch

By default, if you install templates from a Git repository, Spin tries to find a repo tag that matches the version of Spin, and installs from that tag. Failing this, it installs from HEAD. If you would like to install from a specific tag or branch, pass the --branch option:

$ spin templates install --git https://github.com/fermyon/spin --branch spin/templates/v0.8

Installing From a Local Directory

To install templates from your local file system, run spin templates install --dir.

The directory you pass must be one that contains a templates directory. Don’t pass the templates directory itself!

# Expects to find a directory ~/dev/spin-befunge-sdk/templates
$ spin templates install --dir ~/dev/spin-befunge-sdk

See Template Authoring for more details on this layout.

Installing From a Remote Tarball

To install templates from a remote tarball, run spin templates install --tar.

The tarball must have a /templates directory at its root, or have a single root directory and have a templates directory within that. This slightly complicated rule is so that it works correctly with a GitHub release tarball, which always has a root directory named after the release.

$ spin templates install --tar https://github.com/fermyon/spin/archive/refs/tags/v9.8.7.tar.gz

Viewing Your Installed Templates

To see what templates you have installed, run spin templates list.

You can use the --verbose option to see additional information such as where they were installed from.

Uninstalling Templates

You can uninstall templates using spin templates uninstall with the template name:

$ spin templates uninstall redis-befunge

Spin doesn’t currently support uninstalling a whole repo-worth of templates, only individual templates.

Upgrading Templates

When you upgrade Spin, you will typically want to upgrade your templates to match. This means new applications and components will get dependencies that match the Spin version you are using. To do this, run spin templates upgrade:

$ spin templates upgrade
Select repos to upgrade. Use Space to select/deselect and Enter to confirm selection.
  [x] https://github.com/fermyon/spin-python-sdk
  [ ] https://github.com/fermyon/spin (at spin/templates/v1.0)
> [x] https://github.com/fermyon/spin-js-sdk

Use the cursor keys and the space bar to select the repositories you want to upgrade, then hit Enter to upgrade the selected repositories.

Upgrading happens at the repo level, not the individual template level. If you’ve uninstalled templates, upgrading the repo they came from will bring them back.

If you want to upgrade all repositories without being prompted, run spin templates upgrade --all.

As mentioned above, if you want to check which templates come from which repositories use --verbose i.e. spin templates list --verbose.

Upgrading Templates From a Local Directory

spin templates upgrade only upgrades from Git repositories. If you want to upgrade and your templates are in a local directory, run the spin templates install command with the --upgrade flag:

$ spin templates install --dir ~/dev/spin-befunge-sdk --upgrade

Next Steps