Managing Plugins

Plugins are a way to extend the functionality of Spin. Spin provides commands for installing and removing them, so you don’t need to use separate installation tools. When you have installed a plugin into Spin, you can call it as if it were a Spin subcommand. For example, Fermyon Cloud can be accessed with a plugin called cloud, and you run it via the spin cloud command.

Installing Plugins

To install plugins, use the spin plugins install command. You can install plugins by name from a curated repository, or other plugins from a URL or file system.

Installing Well Known Plugins

The Spin maintainers curate a catalogue of “known” plugins. You can install plugins from this catalogue by name:

$ spin plugins install cloud

Spin checks that the plugin is available for your version of Spin and your operating system, and prompts you to confirm the installation. To skip the prompt, pass the --yes flag.

The curated plugins catalogue is stored in a GitHub repository. The first time you install a plugin from the catalogue, Spin clones this repository into a local cache and uses it for future install, list and upgrade commands (similar to OS package managers such as apt). If you want to see new catalogue entries - new plugins or new versions - you must update the local cache by running the spin plugins update command.

Installing a Specific Version of a Plugin

To install a specific version of a plugin, pass the --version flag:

$ spin plugins install cloud --version 0.9.1

Installing a Plugin From a URL

If the plugin you want has been published on the Web but has not been added to the catalogue, you can install it from its manifest URL. The manifest is the JSON document that links to the binaries for different operating systems and processors. For example:

$ spin plugins install --url https://github.com/fermyon/spin-befunge-sdk/releases/download/v1.4.0/befunge2wasm.json

Installing a Plugin From a File

If the plugin you want is in your local file system, you can install it from its manifest file path. The manifest is the JSON document that links to the binaries for different operating systems and processors. For example:

$ spin plugins install --file ~/dev/spin-befunge-sdk/befunge2wasm.json

Running a Plugin

You run plugins in the same way as built-in Spin subcommands. For example:

$ spin cloud --help

Viewing Available Plugins

To see what plugins are available in the catalogue, run spin plugins search:

$ spin plugins search
befunge2wasm 1.4.0 [incompatible]
cloud 0.8.0 [installed]
cloud 0.9.0
trigger-sqs 0.1.0

The annotations by the plugins show their status and compatibility:

AnnotationMeaning
[incompatible]The plugin does not run on your operating system or processor.
[installed]You have the plugin already installed and available to run.
[requires other Spin version]The plugin can run on your operating system and processor, but is not compatible with the version of Spin you are running. The annotation indicates which versions of Spin it is compatible with.

Viewing Installed Plugins

To see only the plugins you have installed, run spin plugins list --installed.

Uninstalling Plugins

You can uninstall plugins using spin plugins uninstall with the plugin name:

$ spin plugins uninstall befunge2wasm

Refreshing the Catalogue

The first time you install a plugin from the catalogue, Spin creates a local cache of the catalogue. It continues to use this local cache for future install, list and upgrade commands; this is similar to OS package managers such as apt, and avoids rate limiting on the catalogue. However, this means that in order to see new catalogue entries - new plugins or new versions - you must first update the cache.

To update your local cache of the catalogue, run spin plugins update.

Upgrading Plugins

To upgrade a plugin to the latest version, first run spin plugins update (to refresh the catalogue), then spin plugins upgrade.

The spin plugins upgrade command has the same options as the spin plugins install command (according to whether the plugin comes from the catalogue, a URL, or a file). For more information, see the command help by running spin plugins upgrade --help.

The upgrade command uses your local cache of the catalogue. This might not include recently added plugins or versions. So always remember to run spin plugins update to refresh your local cache of the catalogue before performing the spin plugins upgrade command.

The following example shows how to upgrade one plugin at a time (i.e. the cloud plugin):

$ spin plugins update
$ spin plugins upgrade cloud

The following example shows how to upgrade all installed plugins at once:

$ spin plugins update
$ spin plugins upgrade --all

Note: The above example only installs plugins from the catalogue

The following example shows additional upgrade options. Specifically, how to upgrade using the path to a remote plugin manifest and how to upgrade using the path to a local plugin manifest:

$ spin plugins upgrade --url https://github.com/fermyon/spin-befunge-sdk/releases/download/v1.7.0/befunge2wasm.json
$ spin plugins upgrade --file ~/dev/spin-befunge-sdk/befunge2wasm.json

Downgrading Plugins

By default, Spin will only upgrade plugins. Pass the --downgrade flag and specify the --version if you want Spin to roll back to an earlier version. The following abridged example (which doesn’t list the full console output for simplicity) lists the versions of plugins, downgrades the cloud to an older version (0.9.0) and then lists the versions again to show the results:

$ spin plugins update
$ spin plugins list
// --snip--
cloud 0.9.0
cloud 0.9.1 [installed]
$ spin plugins upgrade cloud --downgrade --version 0.9.0
$ spin plugins list
// --snip--
cloud 0.9.0 [installed]
cloud 0.9.1

After downgrading, the [installed] indicator is aligned with the 0.9.0 version of cloud, as intended in the example.

Next Steps