Skip to main content
Version: v2.0.0-rc

Wasm Shell CLI Command Reference

Directory Context​

The wash CLI uses automatic project detection similar to git and other GNU tools. This allows you to run wash commands from anywhere within your project without specifying the project path.

shell
~/myproject$ wash dev
~/myproject/wit$ wash build
~/myproject/src$ wash build

When you're outside the project directory, you can use the -C flag to specify the project path. This is useful in CI environments and situations where users can't change directories prior to calling wash.

From your home directory, targeting a project in /tmp:

shell
wash -C /tmp/myproject build

Commands​

Options:​
  • -C <PROJECT_PATH> - Path to the project to run a command against (when outside a project directory)
  • -h, --help - Print help
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -V, --version - Print version

wash build​

Compile a project to a WebAssembly component artifact—i.e., a WebAssembly (.wasm) binary that conforms to the WebAssembly Component Model.

Usage: wash build [OPTIONS]

Options:​
  • -C <PROJECT_PATH> - Path to the project to build (when outside a project directory)
  • --component-path <COMPONENT_PATH> — The expected path to the built Wasm component artifact
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --skip-fetch - Skip fetching WIT dependencies, useful for offline builds
  • --user-config <USER_CONFIG> - Path to user configuration file.
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash completion​

Generate shell completions.

Usage: wash completion [OPTIONS] <SHELL>

  • <SHELL> - The shell to generate completions for [possible values: bash, elvish, fish, powershell, zsh]
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash config​

View configuration for wash.

Usage: wash config [OPTIONS] <COMMAND>

Subcommands:

  • init - Initialize a new configuration file for wash
  • info - Print the current version and local directories used by wash
  • show - Print the current configuration file for wash
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash config init​

Initialize a new configuration file for wash.

Usage: wash config init [OPTIONS]

Options:​
  • --force - Overwrite existing configuration
  • --global - Overwrite global configuration instead of project
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash config info​

Print the current version and local directories used by wash.

Usage: wash config info [OPTIONS]

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash config show​

Print the current configuration file for wash.

Usage: wash config show [OPTIONS]

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash dev​

Start a development server for a Wasm component.

Usage: wash dev [OPTIONS]

Options:​
  • --address <ADDRESS> - The address on which the HTTP server will listen [default: 0.0.0.0:8000]
  • -C <PROJECT_PATH> - Path to the project to build (when outside a project directory)
  • --component-path <COMPONENT_PATH> — The path to the built Wasm file to be used in development
  • --blobstore-root <BLOBSTORE_ROOT> - The root directory for the blobstore to use for wasi:blobstore/blobstore. Defaults to a subfolder in the wash data directory
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --wasi-config <WASI_CONFIG> - Configuration values to use for wasi:config/store in the form of key=value pairs. (Ex: wash dev --wasi-config foo=bar,flim=flam)
  • --tls-cert <TLS_CERT> - Path to TLS certificate file (PEM format) for HTTPS support
  • --tls-key <TLS_KEY> - Path to TLS private key file (PEM format) for HTTPS support
  • --tls-ca <TLS_CA> - Path to CA certificate bundle (PEM format) for client certificate verification (optional)
  • --verbose - Enable verbose output
  • --wasi-webgpu - Enable WASI WebGPU support
  • -h, --help - Print help

wash doctor​

Check the health of your wash installation and environment.

Usage: wash doctor [OPTIONS] <PROJECT_PATH>

  • <PROJECT_PATH> - The path to the project directory [default: .]
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash host​

Act as a wasmCloud host.

Usage: wash host [OPTIONS]

Options:​
  • --data-nats-url <DATA_NATS_URL> - NATS URL for data plane communications [default: nats://localhost:4222]
  • --host-group <HOST_GROUP> - The host group label to assign to the host [default: default]
  • --host-name <HOST_NAME> - The host name to assign to the host
  • --http-addr <HTTP_ADDR> - The address on which the HTTP server will listen
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --scheduler-nats-url <SCHEDULER_NATS_URL> - NATS URL for control plane communications [default: nats://localhost:4222]
  • --verbose - Enable verbose output
  • --wasi-webgpu - Enable WASI WebGPU support
  • -h, --help - Print help

wash inspect​

Inspect a Wasm component's embedded WIT.

Usage: wash inspect [OPTIONS] <COMPONENT_REFERENCE>

  • <COMPONENT_REFERENCE> - Inspect a component by its reference, which can be a local file path, project directory, or remote OCI reference. If omitted or pointing to a directory, attempts to build and inspect a component from that directory.
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash new​

Create a new project from a Git repository.

Usage: wash new [OPTIONS] <GIT>

  • <GIT> - Git repository URL to use as project template.
Options:​
  • --git-ref <GIT> - Git reference (branch, tag, or commit) to checkout
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --name - Project name and local directory to create [default: repository/subfolder name]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --subfolder <SUBFOLDER> - Subdirectory within the git repository to use (only valid with --git)
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash oci​

Push or pull Wasm components to or from an OCI registry.

Usage:: wash oci [OPTIONS] <COMMAND>

Subcommands:

  • pull - Pull a component artifact from an OCI registry.
  • push - Push a component artifact to an OCI registry.
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash oci pull​

Pull a component artifact from an OCI registry.

Usage: wash oci pull [OPTIONS] <REFERENCE> <COMPONENT_PATH>

  • <REFERENCE> - The OCI reference to pull.
  • <COMPONENT_PATH> - The path to write the pulled component to [default: component.wasm]
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash oci push​

Push a component artifact to an OCI registry.

Usage: wash oci push [OPTIONS] <REFERENCE> <COMPONENT_PATH>

  • <REFERENCE> - The OCI reference to push.
  • <COMPONENT_PATH> - The path to the component to push.
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash plugin​

Manage wash plugins.

Usage: wash plugin [OPTIONS] <COMMAND>

Subcommands:

  • install - Install a plugin.
  • uninstall - Uninstall a plugin.
  • list - List installed plugin.
  • test - Test a plugin.
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash plugin install​

Install a plugin from an OCI reference or file.

Usage: wash plugin install [OPTIONS] <SOURCE>

  • <SOURCE> - The source to install from (OCI reference or file path)
Options:​
  • -f, --force - Force overwrite if plugin already exists
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash plugin uninstall​

Uninstall a plugin.

Usage: wash plugin uninstall [OPTIONS] <NAME>

  • <NAME> - The name of the plugin to uninstall.
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash plugin list​

List installed plugins.

Usage: wash plugin list [OPTIONS]

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash plugin test​

Test a plugin.

Usage: wash plugin test [OPTIONS] <PLUGIN> <ARG>...

  • <PLUGIN> - Path to the component or component project to test
  • <ARG>... - The arguments to pass to the plugin command
Options:​
  • --hook <TYPE> - The hook types to test
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash update​

Update wash to the latest version.

Usage: wash update [OPTIONS]

Options:​
  • -d, --dry-run - Check for updates without applying them
  • -f, --force - Force update even if already on the latest version
  • --git <GIT> - Point at a different repository for updates [default: wasmcloud/wash]
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --major - Allow major version updates (breaking changes)
  • --minor - Allow minor version updates (new features, no breaking changes)
  • --patch - Allow only patch updates (bug fixes only)
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --token <TOKEN> - GitHub token for private repository access. Can also be set via GITHUB_TOKEN, GH_TOKEN, or GITHUB_ACCESS_TOKEN environment variables [env: WASH_GITHUB_TOKEN=].
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash wit​

Manage WIT dependencies.

Usage: wash wit [OPTIONS] <COMMAND>

Subcommands:

  • add - Add a new WIT dependency
  • build - Build a WIT package into a Wasm binary
  • clean - Remove fetched dependencies at wit/deps/
  • fetch - Fetch WIT dependencies, reading from wit/world.wit imports
  • remove - Remove a WIT dependency
  • update - Update dependencies to latest compatible versions
Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • -h, --help - Print help

wash wit add​

Add a new WIT dependency.

Usage: wash wit add [OPTIONS] <PACKAGE>

Arguments: <Package> - Package to add (e.g., wasi:keyvalue or wasi:keyvalue@0.2.0-draft)

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • --wit-dir <WIT_DIR> - Path to the WIT directory
  • -h, --help - Print help

wash wit build​

Add a new WIT dependency.

Usage: wash wit build [OPTIONS]

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --output-file <OUTPUT_FILE> - Output file path for the built Wasm package
  • --verbose - Enable verbose output
  • --wit-dir <WIT_DIR> - Path to the WIT directory
  • -h, --help - Print help

wash wit clean​

Remove fetched dependencies at wit/deps/.

Usage: wash wit clean [OPTIONS]

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • --wit-dir <WIT_DIR> - Path to the WIT directory
  • -h, --help - Print help

wash wit fetch​

Fetch WIT dependencies, reading from wit/world.wit imports.

Usage: wash wit fetch [OPTIONS]

Options:​
  • --clean - Remove existing dependencies before fetching
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • --wit-dir <WIT_DIR> - Path to the WIT directory
  • -h, --help - Print help

wash wit remove​

Remove a WIT dependency.

Usage: wash wit remove [OPTIONS] <PACKAGE>

Arguments: <Package> - Package to remove (e.g., wasi:keyvalue)

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • --wit-dir <WIT_DIR> - Path to the WIT directory
  • -h, --help - Print help

wash wit update​

Update dependencies to latest compatible versions.

Usage: wash wit update [OPTIONS] <PACKAGE>

Arguments: <Package> - Specific package to update (e.g., wasi:http). If not specified, updates all packages.

Options:​
  • -l, --log-level <LOG_LEVEL> — Set the log level (trace, debug, info, warn, error) [default: info]
  • --non-interactive - Run in non-interactive mode (skip terminal checks for host exec). Automatically enabled when stdin is not a TTY
  • -o, --output <OUTPUT_FORMAT> — Specify output format (text or json) [default: text]
  • --verbose - Enable verbose output
  • --wit-dir <WIT_DIR> - Path to the WIT directory
  • -h, --help - Print help