1# CLI Options for `wasmtime` 2 3The `wasmtime` CLI is organized into a few subcommands. If no subcommand is 4provided it'll assume `run`, which is to execute a wasm file. The subcommands 5supported by `wasmtime` are: 6 7## `help` 8 9This is a general subcommand used to print help information to the terminal. You 10can execute any number of the following: 11 12```sh 13$ wasmtime help 14$ wasmtime --help 15$ wasmtime -h 16$ wasmtime help run 17$ wasmtime run -h 18``` 19 20When in doubt, try running the `help` command to learn more about functionality! 21 22## `run` 23 24This is the `wasmtime` CLI's main subcommand, and it's also the default if no 25other subcommand is provided. The `run` command will execute a WebAssembly 26module. This means that the module will be compiled to native code, 27instantiated, and then optionally have an export executed. 28 29The `wasmtime` CLI will automatically hook up any WASI-related imported 30functionality, but at this time, if your module imports anything else, it will 31fail instantiation. 32 33The `run` command takes one positional argument, which is the name of the module to run: 34 35```sh 36$ wasmtime run foo.wasm 37$ wasmtime foo.wasm 38``` 39 40Note that the `wasmtime` CLI can take both a binary WebAssembly file (`*.wasm`) 41as well as the text format for WebAssembly (`*.wat`): 42 43```sh 44$ wasmtime foo.wat 45``` 46 47**Wasm Modules** 48 49A Wasm **module** exports raw functions directly. The `run` command accepts an optional `--invoke` argument, which is the name of an exported raw function (of the module) to run: 50 51```sh 52$ wasmtime run --invoke initialize foo.wasm 53``` 54 55**Wasm Components** 56 57A Wasm **component** uses typed interfaces defined by [the component model](https://component-model.bytecodealliance.org/design/components.html). The `run` command also accepts the optional `--invoke` argument for calling an exported function of a **component**. However, the calling of an exported function of a component uses [WAVE](https://github.com/bytecodealliance/wasm-tools/tree/a56e8d3d2a0b754e0465c668f8e4b68bad97590f/crates/wasm-wave#readme)(a human-oriented text encoding of Wasm Component Model values). For example: 58 59```sh 60$ wasmtime run --invoke 'initialize()' foo.wasm 61``` 62 63You 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, 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: 64 65If your function takes a string argument, you surround the string argument in double quotes: 66 67```sh 68$ wasmtime run --invoke 'initialize("hello")' foo.wasm 69``` 70 71And each individual argument within the parentheses is separated by a comma: 72 73```sh 74$ wasmtime run --invoke 'initialize("Pi", 3.14)' foo.wasm 75$ wasmtime run --invoke 'add(1, 2)' foo.wasm 76``` 77 78**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: 79```bash 80wasmtime run - invoke "initialize(\"hello\")" foo.wasm 81``` 82 83## `serve` 84 85The `serve` subcommand runs a WebAssembly component in the `wasi:http/proxy` 86world via the WASI HTTP API, which is available since Wasmtime 18.0.0. The goal 87of this world is to support sending and receiving HTTP requests. 88 89The `serve` command takes one positional argument which is the name of the 90component to run: 91 92```sh 93$ wasmtime serve foo.wasm 94``` 95 96Furthermore, an address can be specified via: 97 98```sh 99$ wasmtime serve --addr=0.0.0.0:8081 foo.wasm 100``` 101 102At the time of writing, the `wasi:http/proxy` world is still experimental and 103requires setup of some `wit` dependencies. For more information, see 104the [hello-wasi-http](https://github.com/sunfishcode/hello-wasi-http/) example. 105 106## `wast` 107 108The `wast` command executes a `*.wast` file which is the test format for the 109official WebAssembly spec test suite. This subcommand will execute the script 110file which has a number of directives supported to instantiate modules, link 111tests, etc. 112 113Executing this looks like: 114 115```sh 116$ wasmtime wast foo.wast 117``` 118 119## `config` 120 121This subcommand is used to control and edit local Wasmtime configuration 122settings. The primary purpose of this currently is to configure [how Wasmtime's 123code caching works](./cli-cache.md). You can create a new configuration file for 124you to edit with: 125 126```sh 127$ wasmtime config new 128``` 129 130And that'll print out the path to the file you can edit. 131 132## `compile` 133 134This subcommand is used to Ahead-Of-Time (AOT) compile a WebAssembly module to produce 135a "compiled wasm" (.cwasm) file. 136 137The `wasmtime run` subcommand can then be used to run a AOT-compiled WebAssembly module: 138 139```sh 140$ wasmtime compile foo.wasm 141$ wasmtime foo.cwasm 142``` 143 144AOT-compiled modules can be run from hosts that are compatible with the target 145environment of the AOT-completed module. 146 147## `settings` 148 149This subcommand is used to print the available Cranelift settings for a given target. 150 151When run without options, it will print the settings for the host target and also 152display what Cranelift settings are inferred for the host: 153 154```sh 155$ wasmtime settings 156``` 157 158## `explore` 159 160This subcommand can be used to explore a `*.cwasm` file and see how it connects 161to the original wasm file in a web browser. This will compile an input wasm 162file and emit an HTML file that can be opened in a web browser: 163 164```sh 165$ wasmtime explore foo.wasm 166Exploration written to foo.explore.html 167``` 168 169The output HTML file can be used to compare what WebAssembly instruction 170compiles to what native instruction. Compilation options can be passed to 171`wasmtime explore` to see the effect of compilation options on generated code. 172 173## `objdump` 174 175Primarily intended as a debugging utility the `objdump` subcommand can be used 176to explore a `*.cwasm` file locally on your terminal. This is roughly modeled 177after native `objdump` binaries themselves: 178 179```sh 180$ wasmtime objdump foo.cwasm 181wasm[0]::function[0]: 182 stp x29, x30, [sp, #-0x10]! 183 mov x29, sp 184 ldr x5, [x2, #0x50] 185 lsl w6, w4, #2 186 ldr w2, [x5, w6, uxtw] 187 ldp x29, x30, [sp], #0x10 188 ret 189``` 190 191You can also pass various options to configure and annotate the output: 192 193```sh 194$ wasmtime objdump foo.cwasm --addresses --bytes --addrma 19500000000 wasm[0]::function[0]: 196 0: fd 7b bf a9 stp x29, x30, [sp, #-0x10]! 197 4: fd 03 00 91 mov x29, sp 198 8: 45 28 40 f9 ldr x5, [x2, #0x50] 199 ╰─╼ addrmap: 0x23 200 c: 86 74 1e 53 lsl w6, w4, #2 201 ╰─╼ addrmap: 0x22 202 10: a2 48 66 b8 ldr w2, [x5, w6, uxtw] 203 ╰─╼ addrmap: 0x23 204 14: fd 7b c1 a8 ldp x29, x30, [sp], #0x10 205 ╰─╼ addrmap: 0x26 206 18: c0 03 5f d6 ret 207``` 208 209# Additional options 210Many of the above subcommands also take additional options. For example, 211- run 212- serve 213- compile 214- explore 215- wast 216 217are all subcommands which can take additional CLI options of the format 218 219```sh 220Options: 221 -O, --optimize <KEY[=VAL[,..]]> 222 Optimization and tuning related options for wasm performance, `-O help` to see all 223 224 -C, --codegen <KEY[=VAL[,..]]> 225 Codegen-related configuration options, `-C help` to see all 226 227 -D, --debug <KEY[=VAL[,..]]> 228 Debug-related configuration options, `-D help` to see all 229 230 -W, --wasm <KEY[=VAL[,..]]> 231 Options for configuring semantic execution of WebAssembly, `-W help` to see all 232 233 -S, --wasi <KEY[=VAL[,..]]> 234 Options for configuring WASI and its proposals, `-S help` to see all 235``` 236 237For example, adding `--optimize opt-level=0` to a `wasmtime compile` subcommand 238will turn off most optimizations for the generated code. 239 240## CLI options using TOML file 241Most key-value options that can be provided using the `--optimize`, `--codegen`, 242`--debug`, `--wasm`, and `--wasi` flags can also be provided using a TOML 243file using the `--config <FILE>` cli flag, by putting the key-value inside a TOML 244table with the same name. 245 246For example, with a TOML file like this 247```toml 248[optimize] 249opt-level = 0 250``` 251the command 252```sh 253$ wasmtime compile --config config.toml 254``` 255would be the same as 256```sh 257$ wasmtime compile --optimize opt-level=0 258``` 259assuming the TOML file is called `config.toml`. Of course you can put as many 260key-value pairs as you want in the TOML file. 261 262Options on the CLI take precedent over options specified in a configuration 263file, meaning they're allowed to shadow configuration values in a TOML 264configuration file. 265