Managing Plugins
- Installing Plugins
- Running a Plugin
- Viewing Available Plugins
- Uninstalling Plugins
- Refreshing the Catalogue
- Upgrading Plugins
- Downgrading Plugins
- Next Steps
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 thespin 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:
Annotation | Meaning |
---|---|
[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 runspin plugins update
to refresh your local cache of the catalogue before performing thespin 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.