CLI Options - Wasmtime

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# CLI Options for `wasmtime`

The `wasmtime` CLI is organized into a few subcommands. If no subcommand is provided it'll assume `run`, which is to execute a wasm file. The subcommands supported by `wasmtime` are:

## `help`

This is a general subcommand used to print help information to the terminal. You can execute any number of the following:

    wasmtime help
    wasmtime --help
    wasmtime -h
    wasmtime help run
    wasmtime run -h

When in doubt, try running the `help` command to learn more about functionality!

## `run`

This is the `wasmtime` CLI's main subcommand, and it's also the default if no other subcommand is provided. The `run` command will execute a WebAssembly module. This means that the module will be compiled to native code, instantiated, and then optionally have an export executed.

The `wasmtime` CLI will automatically hook up any WASI-related imported functionality, but at this time, if your module imports anything else, it will fail instantiation.

The `run` command takes one positional argument, which is the name of the module to run:

    wasmtime run foo.wasm
    wasmtime foo.wasm

Note that the `wasmtime` CLI can take both a binary WebAssembly file (`*.wasm`) as well as the text format for WebAssembly (`*.wat`):

    wasmtime foo.wat

#### Running WebAssembly CLI programs

WebAssembly modules or components can behave like a CLI program which means they're intended to look like a normal OS executable with a `main` function and run once to completion. This is the default mode of running a wasm provided to Wasmtime.

For core WebAssembly modules this means that the function exported as an empty string, or the `_start` export, is invoked. For WebAssembly components this means that the `wasi:cli/run` interface is executed.

For both core modules and components, CLI arguments are passed via WASI. Core modules receive arguments via WASIp1 APIs and components receive arguments via WASIp2 or later APIs. Arguments, flags, etc., are passed to the WebAssembly file after the file itself. For example,

    wasmtime foo.wasm --bar baz

Will pass `["foo.wasm", "--bar", "baz"]` as the list of arguments to the module. Note that flags for Wasmtime must be passed before the WebAssembly file, not afterwards. For example,

    wasmtime foo.wasm --dir .

Will pass `--dir .` to the `foo.wasm` program, not Wasmtime. If you want to mount the current directory you instead need to invoke

    wasmtime --dir . foo.wasm

All Wasmtime options must come before the WebAssembly file provided. All arguments afterwards are passed to the WebAssembly file itself.

#### Running Custom Module exports

If you're not running a "command" but want to run a specific export of a WebAssembly core module you can use the `--invoke` argument:

    wasmtime run --invoke initialize foo.wasm

This will invoke the `initialize` export of the `foo.wasm` module.

When invoking a WebAssembly function arguments to the function itself are parsed from CLI arguments. For example an `i32` argument to a WebAssembly module is parsed as a CLI argument for the module:

    wasmtime run --invoke add add.wasm 1 2

Note though that this syntax is unstable at this time and may change in the future. If you'd like to rely on this please open an issue, otherwise we request that you please don't rely on the exact output here.

#### Running Custom Component exports

Like core modules Wasmtime supports invoking arbitrary component exports. Components can export typed interfaces defined by the component model. The `--invoke` argument is supported to skip calling `wasi:cli/run` and invoke a specific typed export instead. Arguments are passed with WAVE ,a human-oriented text encoding of Wasm Component Model values. For example:

    wasmtime run --invoke 'initialize()' foo.wasm

You will notice that (when using WAVE) the exported function's name and exported function's parentheses are both enclosed in one set of single quotes, i.e. `'initialize()'`. This treats the exported function as a single argument in a Unix shell and prevents issues with shell interpretation and signifies function invocation (as apposed to the function name just being referenced). Using WAVE (when calling exported functions of Wasm components) helps to distinguish function calls from other kinds of string arguments. Below are some more examples:

If your function takes a string argument, you surround the string argument in double quotes:

    wasmtime run --invoke 'initialize("hello")' foo.wasm

And each individual argument within the parentheses is separated by a comma:

    wasmtime run --invoke 'initialize("Pi", 3.14)' foo.wasm
    wasmtime run --invoke 'add(1, 2)' foo.wasm

Please note: If you enclose your whole function call using double quotes, your string argument will require its double quotes to be escaped (escaping quotes is more complicated and harder to read and therefore not ideal). For example:

    wasmtime run - invoke "initialize(\"hello\")" foo.wasm

## `serve`

The `serve` subcommand runs a WebAssembly component in the `wasi:http/proxy` world via the WASI HTTP API, which is available since Wasmtime 18.0.0. The goal of this world is to support sending and receiving HTTP requests.

The `serve` command takes one positional argument which is the name of the component to run:

    wasmtime serve foo.wasm

Furthermore, an address can be specified via:

    wasmtime serve --addr=0.0.0.0:8081 foo.wasm

At the time of writing, the `wasi:http/proxy` world is still experimental and requires setup of some `wit` dependencies. For more information, see the hello-wasi-http example.

## `wast`

The `wast` command executes a `*.wast` file which is the test format for the official WebAssembly spec test suite. This subcommand will execute the script file which has a number of directives supported to instantiate modules, link tests, etc.

Executing this looks like:

    wasmtime wast foo.wast

## `config`

This subcommand is used to control and edit local Wasmtime configuration settings. The primary purpose of this currently is to configure how Wasmtime's code caching works. You can create a new configuration file for you to edit with:

    wasmtime config new

And that'll print out the path to the file you can edit.

## `compile`

This subcommand is used to Ahead-Of-Time (AOT) compile a WebAssembly module to produce a "compiled wasm" (.cwasm) file.

The `wasmtime run` subcommand can then be used to run a AOT-compiled WebAssembly module:

    wasmtime compile foo.wasm
    wasmtime foo.cwasm

AOT-compiled modules can be run from hosts that are compatible with the target environment of the AOT-completed module.

## `settings`

This subcommand is used to print the available Cranelift settings for a given target.

When run without options, it will print the settings for the host target and also display what Cranelift settings are inferred for the host:

    wasmtime settings

## `explore`

This subcommand can be used to explore a `*.cwasm` file and see how it connects to the original wasm file in a web browser. This will compile an input wasm file and emit an HTML file that can be opened in a web browser:

    $ wasmtime explore foo.wasm
    Exploration written to foo.explore.html

The output HTML file can be used to compare what WebAssembly instruction compiles to what native instruction. Compilation options can be passed to `wasmtime explore` to see the effect of compilation options on generated code.

## `objdump`

Primarily intended as a debugging utility the `objdump` subcommand can be used to explore a `*.cwasm` file locally on your terminal. This is roughly modeled after native `objdump` binaries themselves:

    $ wasmtime objdump foo.cwasm
    wasm[0]::function[0]:
                stp     x29, x30, [sp, #-0x10]!
                mov     x29, sp
                ldr     x5, [x2, #0x50]
                lsl     w6, w4, #2
                ldr     w2, [x5, w6, uxtw]
                ldp     x29, x30, [sp], #0x10
                ret

You can also pass various options to configure and annotate the output:

    $ wasmtime objdump foo.cwasm --addresses --bytes --addrma
    00000000 wasm[0]::function[0]:
             0: fd 7b bf a9                  stp     x29, x30, [sp, #-0x10]!
             4: fd 03 00 91                  mov     x29, sp
             8: 45 28 40 f9                  ldr     x5, [x2, #0x50]
                                              ╰─╼ addrmap: 0x23
             c: 86 74 1e 53                  lsl     w6, w4, #2
                                              ╰─╼ addrmap: 0x22
            10: a2 48 66 b8                  ldr     w2, [x5, w6, uxtw]
                                              ╰─╼ addrmap: 0x23
            14: fd 7b c1 a8                  ldp     x29, x30, [sp], #0x10
                                              ╰─╼ addrmap: 0x26
            18: c0 03 5f d6                  ret

# Additional options

Many of the above subcommands also take additional options. For example,

- run
- serve
- compile
- explore
- wast

are all subcommands which can take additional CLI options of the format

    Options:
      -O, --optimize <KEY[=VAL[,..]]>
              Optimization and tuning related options for wasm performance, `-O help` to see all

      -C, --codegen <KEY[=VAL[,..]]>
              Codegen-related configuration options, `-C help` to see all

      -D, --debug <KEY[=VAL[,..]]>
              Debug-related configuration options, `-D help` to see all

      -W, --wasm <KEY[=VAL[,..]]>
              Options for configuring semantic execution of WebAssembly, `-W help` to see all

      -S, --wasi <KEY[=VAL[,..]]>
              Options for configuring WASI and its proposals, `-S help` to see all

For example, adding `--optimize opt-level=0` to a `wasmtime compile` subcommand will turn off most optimizations for the generated code.

## CLI options using TOML file

Most key-value options that can be provided using the `--optimize`, `--codegen`, `--debug`, `--wasm`, and `--wasi` flags can also be provided using a TOML file using the `--config <FILE>` cli flag, by putting the key-value inside a TOML table with the same name.

For example, with a TOML file like this

    [optimize]
    opt-level = 0

the command

    wasmtime compile --config config.toml

would be the same as

    wasmtime compile --optimize opt-level=0

assuming the TOML file is called `config.toml`. Of course you can put as many key-value pairs as you want in the TOML file.

Options on the CLI take precedent over options specified in a configuration file, meaning they're allowed to shadow configuration values in a TOML configuration file.