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