Skip to main content
Version: next

Wasm Shell Plugins

The Wasm Shell (wash) CLI is extensible via a component-driven plugin system. New integrations and functionality can be implemented across any language that compiles to a WebAssembly component target, and then the component can plug in directly to wash.

First-party plugins​

The following plugins are available from the wasmCloud project:

  • blobstore-filesystem: Extends wash dev to support the wasi:blobstore interface backed by local filesystem. (Source | OCI)
  • aspire-otel: Launches the Aspire dashboard. (Source)

Subcommands​

The wash plugin command takes the following subcommands:

  • install - Install a plugin from an OCI reference or file
  • uninstall - Uninstall a plugin
  • list - List installed plugins
  • test - Test a plugin

Install a plugin​

Install a plugin from an OCI reference or file:

shell
wash plugin install <SOURCE>

To install a plugin from an OCI reference, target the OCI artifact with wash plugin intall. For example, to install the blobstore-filesystem plugin:

shell
wash plugin install ghcr.io/wasmcloud/wash-plugins/blobstore-filesystem:0.1.0

To install a plugin from source, build the component with wash build and then target the component binary with wash plugin install. For example, to build the blobstore-filesystem component from source:

shell
git clone https://github.com/wasmCloud/wash.git
shell
cd wash/plugins/blobstore-filesystem
shell
wash build
shell
wash plugin install ./target/wasm32-wasip2/release/blobstore_filesystem.wasm

See the command reference for complete command options.

Uninstall a plugin​

Uninstall a plugin by name:

shell
wash plugin uninstall <NAME>

See the command reference for complete command options.

List installed plugins​

List installed plugins:

shell
wash plugin list

See the command reference for complete command options.

Test a plugin​

Test a plugin by filepath to the component or component project, and the argument you wish to pass to the plugin:

shell
wash plugin test <PLUGIN> <ARG>

See the command reference for complete command options.

Developing plugins​

Under rapid development

The plugin model is under rapid development, and the wasmcloud:wash/plugin interface is subject to regular changes. Feedback on the interface is welcome on the wash Issues page.

Wasm Shell plugins are standard component projects, with a wit directory and WIT world defining imports and exports. You can find examples in the plugins subfolder on GitHub.

Plugins export on the wasmcloud:wash/plugin interface, and have access to the following WASI interfaces:

  1. wasi@0.2 core interfaces (cli, filesystem, io)
  2. wasi:http/incoming-handler: Enables command plugins (see below) to support use-cases for components that can be interacted with over HTTP
  3. wasi:http/outgoing-handler: To make outgoing HTTP requests
  4. wasi:config/runtime: For configuration fetching
  5. wasi:logging/logging: For structured/leveled output

wash plugins are integrated into multiple places in the lifecycle of the CLI:

Hooks​

Plugins can run at various hook points before and after any built-in wash command:

  1. BeforeDev: Before a wash dev session (e.g., Launch an OTEL dashboard for tracing/logging/metrics data)
  2. BeforePush: Before an OCI push (e.g., Add an additional annotation onto the OCI artifact config)
  3. AfterBuild: After a Wasm binary build (e.g., Use cosign to sign a component)
  4. AfterDev: After a wash dev session (e.g., Inspect the built component and generate a deployment manifest for it)

Commands​

Plugins can also register top-level commands in wash, or register top-level commands with a list of subcommands.

Command plugins are registered directly into the CLI parsing and appear just like built-in commands, but they execute as component plugins. For example, the oauth plugin launches an HTTP server on execution of the command. Command plugins do not have their own hooks.

You can see the hook and command flow in the diagram below:

wash plugin flow