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.