wash - The Wasm Shell

wash is the comprehensive command-line tool for developing, building, and managing WebAssembly components. It provides an intuitive developer experience for the modern Wasm ecosystem, from project scaffolding to building and pushing components to OCI registries.

Features

• Project Creation: Generate new WebAssembly component projects from templates
• Multi-Language Build System: Compile components for multiple languages (Rust, Go, TypeScript)
• Development Loop: Built-in hot-reload development server (wash dev)
• OCI Registry Integration: Push and pull components to/from OCI-compatible registries
• Plugin System: Extensible architecture with WebAssembly-based plugins
• Component Inspection: Analyze component WIT interfaces and metadata
• Environment Health Checks: Built-in diagnostics and system verification
• Configuration Management: Hierarchical configuration with global and project-level settings
• Self-Updates: Keep wash up-to-date with the latest features and fixes

Installation

Pre-built Binaries

Download the latest release for your platform from GitHub Releases.

Install

Quick install (latest release)

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/wasmcloud/wash/refs/heads/main/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/wasmcloud/wash/refs/heads/main/install.ps1 | iex

Make sure to move wash to somewhere in your PATH.

From Source

git clone https://github.com/wasmcloud/wash.git
cd wash
cargo install --path .

Quick Start

1. Check your environment:

   wash doctor

2. Create a new component:

   wash new

3. Build your component:

   wash build ./http-hello-world

4. Start a development loop

   wash dev ./http-hello-world

5. Keep wash updated:

   wash update

Commands

Command	Description
wash build	Build a Wasm component
wash config	View and manage wash configuration
wash completion	Generate shell completion scripts for wash
wash dev	Start a development server for a Wasm component with hot-reload
wash doctor	Check the health of your wash installation and environment
wash host	Act as a host.
wash inspect	Inspect a Wasm component's embedded WIT interfaces
wash new	Create a new project from a template or git repository
wash oci	Push or pull Wasm components to/from an OCI registry
wash plugin	Manage wash plugins
wash update	Update wash to the latest version
wash wit	Manage WIT dependencies
wash help	Print this message or the help of the given subcommand(s)

Run wash --help or wash <command> --help for detailed usage information.

Plugin Commands

wash also supports custom commands through its plugin system. Plugins are automatically discovered and made available as subcommands.

Plugin System

wash features an extensible plugin architecture built on WebAssembly:

• Built-in Plugins: oauth, blobstore-filesystem, aspire-otel
• Platform Integration: Plugins can integrate wash with specific platforms (like wasmCloud)
• Custom Plugins: Write your own plugins using the WebAssembly Component Model
• Automatic Discovery: Plugins in the plugins/ directory are automatically loaded
• Hook System: Plugins can register pre and post-command hooks for workflow customization

Use wash plugin --help to see plugin management commands.

Shell Completion

Zsh

For zsh completion, please run:

mkdir -p ~/.zsh/completion
wash completion zsh > ~/.zsh/completion/_wash

and put the following in ~/.zshrc:

fpath=(~/.zsh/completion $fpath)

Note if you're not running a distribution like oh-my-zsh you may first have to enable autocompletion (and put in ~/.zshrc to make it persistent):

autoload -Uz compinit && compinit

Bash

To enable bash completion, run the following, or put it in ~/.bashrc or ~/.profile:

. <(wash completion bash)

Fish

The below commands can be used for fish auto completion:

mkdir -p ~/.config/fish/completions
wash completion fish > ~/.config/fish/completions/wash.fish

Powershell

The below command can be referred for setting it up. Please note that the path might be different depending on your system settings.

wash completion powershell > $env:UserProfile\\Documents\\WindowsPowerShell\\Scripts\\wash.ps1

Architecture

wash is built with the following key principles:

• Component-First: Native support for the WebAssembly Component Model
• Language Agnostic: Support for Rust, Go (TinyGo), TypeScript, and more
• OCI Compatible: Components are stored and distributed using OCI registries
• Portable Components: Produces WebAssembly components that are runtime-agnostic and compatible with any Component Model runtime
• Wasmtime-Powered: Uses Wasmtime for local component execution and development workflows
• Extensible: Plugin system allows integration with different platforms and workflows
• Developer Experience: Hot-reload development loops and comprehensive tooling

Wash & Kubernetes

Start kind cluster:

make kind-setup

Install chart with pre-configured values:

make helm-install

Wait for all pods to come online.

Check if hosts registered correctly:

❯ kubectl get host
NAME                    HOSTID                                 HOSTGROUP         READY   AGE
near-jam-0148           a67300ea-558b-4bb7-b126-253e66d997ae   public-ingress    True    2m10s
nonchalant-crown-3127   8cf2c415-409f-4dd8-b334-8a9dbb2d4aa4   default           True    2m10s
obscene-thunder-6047    2f5aa990-c06a-4d1c-9dcf-edc4a8535fd5   private-ingress   True    2m9s

• public-ingress: Hostgroup with HTTP enabled and bound to localhost port 80, simulating a load-balancer
• private-ingress: Hostgroup with HTTP enabled and cluster-only access, simulating an internal load-balancer ( Kubernetes Service Name hostgroup-private-ingress )
• default: Hostgroup with no incoming HTTP, for wasmcloud:messaging handlers & Services

In this setup, HTTP workloads usually go to public-ingress.

Documentation

• WebAssembly Component Model - Learn about the component model
• WASI Preview 2 - WebAssembly System Interface
• wasmCloud Documentation - Platform integration via plugins
• Contributing Guide - How to contribute to this project

Support

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Community support and Q&A
• WebAssembly Community - Broader WebAssembly ecosystem

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.