Lib.rs

› WebAssembly › wasmcloud-core
#wasmcloud #capability-provider #wash #wasm-component #cli-tool

bin+lib wash-cli

wasmCloud Shell (wash) CLI tool

by The wasmCloud Team. Owned by Brooks Townsend, Kevin Hoffman, wasmCloud Automation Bot.

68 releases (26 breaking)

new 0.27.0 Apr 17, 2024
0.27.0-alpha.1 Mar 18, 2024
0.26.0 Feb 14, 2024
0.25.0 Dec 29, 2023
0.1.7 Nov 10, 2020

#492 in WebAssembly

Download history 8/week @ 2023-12-28 53/week @ 2024-02-08 86/week @ 2024-02-15 54/week @ 2024-02-22 46/week @ 2024-02-29 7/week @ 2024-03-07 107/week @ 2024-03-14 50/week @ 2024-03-21 125/week @ 2024-03-28 261/week @ 2024-04-04

545 downloads per month

Apache-2.0 and LGPL-3.0-or-later

2MB
21K SLoC

Latest Release Rust Build Rust Version Contributors Good first issues wash-cli

                                     _                 _    _____ _          _ _
                                ____| |               | |  / ____| |        | | |
 __      ____ _ ___ _ __ ___  / ____| | ___  _   _  __| | | (___ | |__   ___| | |
 \ \ /\ / / _` / __| '_ ` _ \| |    | |/ _ \| | | |/ _` |  \___ \| '_ \ / _ \ | |
  \ V  V / (_| \__ \ | | | | | |____| | (_) | |_| | (_| |  ____) | | | |  __/ | |
   \_/\_/ \__,_|___/_| |_| |_|\_____|_|\___/ \__,_|\__,_| |_____/|_| |_|\___|_|_|

Why wash

wash is a bundle of command line tools that, together, form a comprehensive CLI for wasmCloud development. Everything from generating new wasmCloud projects, managing cryptographic signing keys, and interacting with OCI compliant registries is contained within the subcommands of wash. Our goal with wash is to encapsulate our tools into a single binary to make developing WebAssembly with wasmCloud painless and simple.

Installing wash

Cargo

cargo install wash-cli

Linux (deb/rpm + apt)

# Debian / Ubuntu (deb)
curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.deb.sh | sudo bash
# Fedora (rpm)
curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.rpm.sh | sudo bash

sudo apt install wash

Linux (snap)

sudo snap install wash --edge --devmode

Linux (brew)

brew install wasmcloud/wasmcloud/wash

MacOS (brew)

brew install wasmcloud/wasmcloud/wash

Windows (choco)

choco install wash

Nix

nix run github:wasmCloud/wash

Using wash

wash has multiple subcommands, each specializing in one specific area of the wasmCloud development process.

build

Builds and signs the actor, provider, or interface as defined in a wasmcloud.toml file. Will look for configuration file in directory where command is being run.
There are three main sections of a wasmcloud.toml file: common config, language config, and type config.

Common Config

Setting Type Default Description
name string Name of the project
version string Semantic version of the project
path string {pwd} Path to the project directory to determine where built and signed artifacts are output
language enum [rust, tinygo, other] Language that actor or provider is written in
type enum [actor, provider, interface ] Type of wasmcloud artifact that is being generated
wasm_bin_name string "name" setting Expected name of the wasm module binary that will be generated

Language Config - [tinygo]

[!IMPORTANT] To build components written in Go, wash uses the tinygo compiler toolchain. To set up TinyGo, we recommend the official installation instructions.

Setting Type Default Description
tinygo_path string which tinygo The path to the tinygo binary

Language Config - [rust]

[!IMPORTANT] To build components written in Rust, wash uses the cargo toolchain. To set up Rust, we recommend using rustup.

Setting Type Default Description
cargo_path string which cargo The path to the cargo binary
target_path string ./target Path to cargo/rust's target directory

Language Config - [other]

If you are using a language other than Rust or Go, you can designate your language as any string (ex. javascript).

Since wash will be unable to infer the build toolchain from the language you provide, you must supply the build_command and the path to the build_artifact so that the artifact can be built and found before signing.

Type Config - [actor]

Setting Type Default Description
claims list [] The list of provider claims that this actor requires. eg. ["wasmcloud:httpserver", "wasmcloud:blobstore"]
registry string localhost:8080 The registry to push to. eg. "localhost:8080"
push_insecure boolean false Whether to push to the registry insecurely
key_directory string ~/.wash/keys The directory to store the private signing keys in
wasm_target string wasm32-unknown-unknown Compile target. Can be one of: wasm32-unknown-unknown, wasm32-wasi-preview1, wasm32-wasi-preview2
call_alias string The call alias of the actor
build_artifact string /path/to/project/build/{filename}.wasm Optional override path where wash can expect to find the built and unsigned WebAssembly artifact
build_command string Language specific command Optional command to run instead of inferring the default language toolchain build command. Supports commands in the format of command ...arg. wash expects that the build command will result in an artifact under the project build folder named either {wasm_bin_name}.wasm if supplied or {name}.wasm otherwise.
destination string /path/to/project/build/{filename}_s.wasm File path to output the destination WebAssembly artifact after building and signing.

Type Config - [provider]

Setting Type Default Description
capability_id string The capability ID of the provider
vendor string The vendor name of the provider

Type Config - [interface]

Setting Type Default Description
html_target string ./html Directory to output HTML
codegen_config string . Path to codegen.toml file

Example

name = "echo"
language = "rust"
type = "actor"
version = "0.1.0"

[actor]
claims = ["wasmcloud:httpserver"]

[rust]
cargo_path = "/tmp/cargo"

call

Invoke a wasmCloud actor directly with a specified payload. This allows you to test actor handlers without the need to manage capabilities and link definitions for a rapid development feedback loop.

claims

Generate JWTs for components, capability providers, accounts and operators. Sign actor modules with claims including capability IDs, expiration, and keys to verify identity. Inspect actor modules to view their claims.

completions

Generate shell completion files for Zsh, Bash, Fish, or PowerShell.

ctl

Interact directly with a wasmCloud control-interface, allowing you to imperatively schedule components, providers and modify configurations of a wasmCloud host. Can be used to interact with local and remote control-interfaces.

ctx

Automatically connect to your previously launched wasmCloud lattice with a managed context or use contexts to administer remote wasmCloud lattices.

drain

Manage contents of the local wasmCloud cache. wasmCloud manages a local cache that will avoid redundant fetching of content when possible. drain allows you to manually clear that cache to ensure you're always pulling the latest versions of components and providers that are hosted in remote OCI registries.

gen

Generate code from smithy files using weld codegen. This is the primary method of generating actor and capability provider code from .smithy interfaces. Currently has first class support for Rust components and providers, along with autogenerated HTML documentation.

keys

Generate ed25519 keys for securely signing and identifying wasmCloud entities (components, providers, hosts). Read more about our decision to use ed25519 keys in our ADR.

lint

Perform lint checks on .smithy models, outputting warnings for best practices with interfaces.

new

Create new wasmCloud projects from predefined templates. This command is a one-stop-shop for creating new components, providers, and interfaces for all aspects of your application.

par

Create, modify and inspect provider archives, a TAR format that contains a signed JWT and OS/Architecture specific binaries for native capability providers.

reg

Push and Pull components and capability providers to/from OCI compliant registries. Used extensively in our own CI/CD and in local development, where a local registry is used to store your development artifacts.

up

Bootstrap a wasmCloud environment in one easy command, supporting both launching NATS and wasmCloud in the background as well as an "interactive" mode for shorter lived hosts.

validate

Perform validation checks on .smithy models, ensuring that your interfaces are valid and usable for codegen and development.

Shell auto-complete

wash has support for autocomplete for Zsh, Bash, Fish, and PowerShell. See Completions for instructions for installing autocomplete for your shell.

Contributing to wash

Visit CONTRIBUTING.md for more information on how to contribute to wash project.

Dependencies

~80MB
~1.5M SLoC