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```console 13wasmtime help 14wasmtime --help 15wasmtime -h 16wasmtime help run 17wasmtime 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```console 36wasmtime run foo.wasm 37wasmtime 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```console 44wasmtime foo.wat 45``` 46 47#### Running WebAssembly CLI programs 48 49WebAssembly modules or components can behave like a CLI program which means 50they're intended to look like a normal OS executable with a `main` function and 51run once to completion. This is the default mode of running a wasm provided to 52Wasmtime. 53 54For core WebAssembly modules this means that the function exported as an empty 55string, or the `_start` export, is invoked. For WebAssembly components this 56means that the `wasi:cli/run` interface is executed. 57 58For both core modules and components, CLI arguments are passed via WASI. Core 59modules receive arguments via WASIp1 APIs and components receive arguments via 60WASIp2 or later APIs. Arguments, flags, etc., are passed to the WebAssembly file 61after the file itself. For example, 62 63```console 64wasmtime foo.wasm --bar baz 65``` 66 67Will pass `["foo.wasm", "--bar", "baz"]` as the list of arguments to the module. 68Note that flags for Wasmtime must be passed before the WebAssembly file, not 69afterwards. For example, 70 71```console 72wasmtime foo.wasm --dir . 73``` 74 75Will pass `--dir .` to the `foo.wasm` program, not Wasmtime. If you want to 76mount the current directory you instead need to invoke 77 78```console 79wasmtime --dir . foo.wasm 80``` 81 82All Wasmtime options must come before the WebAssembly file provided. All 83arguments afterwards are passed to the WebAssembly file itself. 84 85#### Running Custom Module exports 86 87If you're not running a "command" but want to run a specific export of a 88WebAssembly core module you can use the `--invoke` argument: 89 90```console 91wasmtime run --invoke initialize foo.wasm 92``` 93 94This will invoke the `initialize` export of the `foo.wasm` module. 95 96When invoking a WebAssembly function arguments to the function itself are parsed 97from CLI arguments. For example an `i32` argument to a WebAssembly module is 98parsed as a CLI argument for the module: 99 100```console 101wasmtime run --invoke add add.wasm 1 2 102``` 103 104Note though that this syntax is unstable at this time and may change in the 105future. If you'd like to rely on this please open an issue, otherwise we request 106that you please don't rely on the exact output here. 107 108#### Running Custom Component exports 109 110Like core modules Wasmtime supports invoking arbitrary component exports. 111Components can export typed interfaces defined by [the component 112model](https://component-model.bytecodealliance.org/design/components.html). The 113`--invoke` argument is supported to skip calling `wasi:cli/run` and invoke a 114specific typed export instead. Arguments are passed with 115[WAVE](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-wave#readme) 116,a human-oriented text encoding of Wasm Component Model values. For example: 117 118```console 119wasmtime run --invoke 'initialize()' foo.wasm 120``` 121 122You will notice that (when using WAVE) the exported function's name and exported 123function's parentheses are both enclosed in one set of single quotes, i.e. 124`'initialize()'`. This treats the exported function as a single argument in a 125Unix shell and prevents issues with shell interpretation and signifies function 126invocation (as apposed to the function name just being referenced). Using WAVE 127(when calling exported functions of Wasm components) helps to distinguish 128function calls from other kinds of string arguments. Below are some more 129examples: 130 131If your function takes a string argument, you surround the string argument in 132double quotes: 133 134```console 135wasmtime run --invoke 'initialize("hello")' foo.wasm 136``` 137 138And each individual argument within the parentheses is separated by a comma: 139 140```console 141wasmtime run --invoke 'initialize("Pi", 3.14)' foo.wasm 142wasmtime run --invoke 'add(1, 2)' foo.wasm 143``` 144 145**Please note:** If you enclose your whole function call using double quotes, 146your string argument will require its double quotes to be escaped (escaping 147quotes is more complicated and harder to read and therefore not ideal). For 148example: 149 150```bash 151wasmtime run - invoke "initialize(\"hello\")" foo.wasm 152``` 153 154## `serve` 155 156The `serve` subcommand runs a WebAssembly component in the `wasi:http/proxy` 157world via the WASI HTTP API, which is available since Wasmtime 18.0.0. The goal 158of this world is to support sending and receiving HTTP requests. 159 160The `serve` command takes one positional argument which is the name of the 161component to run: 162 163```console 164wasmtime serve foo.wasm 165``` 166 167Furthermore, an address can be specified via: 168 169```console 170wasmtime serve --addr=0.0.0.0:8081 foo.wasm 171``` 172 173At the time of writing, the `wasi:http/proxy` world is still experimental and 174requires setup of some `wit` dependencies. For more information, see 175the [hello-wasi-http](https://github.com/sunfishcode/hello-wasi-http/) example. 176 177## `wast` 178 179The `wast` command executes a `*.wast` file which is the test format for the 180official WebAssembly spec test suite. This subcommand will execute the script 181file which has a number of directives supported to instantiate modules, link 182tests, etc. 183 184Executing this looks like: 185 186```console 187wasmtime wast foo.wast 188``` 189 190## `config` 191 192This subcommand is used to control and edit local Wasmtime configuration 193settings. The primary purpose of this currently is to configure [how Wasmtime's 194code caching works](./cli-cache.md). You can create a new configuration file for 195you to edit with: 196 197```console 198wasmtime config new 199``` 200 201And that'll print out the path to the file you can edit. 202 203## `compile` 204 205This subcommand is used to Ahead-Of-Time (AOT) compile a WebAssembly module to produce 206a "compiled wasm" (.cwasm) file. 207 208The `wasmtime run` subcommand can then be used to run a AOT-compiled WebAssembly module: 209 210```console 211wasmtime compile foo.wasm 212wasmtime foo.cwasm 213``` 214 215AOT-compiled modules can be run from hosts that are compatible with the target 216environment of the AOT-completed module. 217 218## `settings` 219 220This subcommand is used to print the available Cranelift settings for a given target. 221 222When run without options, it will print the settings for the host target and also 223display what Cranelift settings are inferred for the host: 224 225```console 226wasmtime settings 227``` 228 229## `explore` 230 231This subcommand can be used to explore a `*.cwasm` file and see how it connects 232to the original wasm file in a web browser. This will compile an input wasm 233file and emit an HTML file that can be opened in a web browser: 234 235```console 236$ wasmtime explore foo.wasm 237Exploration written to foo.explore.html 238``` 239 240The output HTML file can be used to compare what WebAssembly instruction 241compiles to what native instruction. Compilation options can be passed to 242`wasmtime explore` to see the effect of compilation options on generated code. 243 244## `objdump` 245 246Primarily intended as a debugging utility the `objdump` subcommand can be used 247to explore a `*.cwasm` file locally on your terminal. This is roughly modeled 248after native `objdump` binaries themselves: 249 250```console 251$ wasmtime objdump foo.cwasm 252wasm[0]::function[0]: 253 stp x29, x30, [sp, #-0x10]! 254 mov x29, sp 255 ldr x5, [x2, #0x50] 256 lsl w6, w4, #2 257 ldr w2, [x5, w6, uxtw] 258 ldp x29, x30, [sp], #0x10 259 ret 260``` 261 262You can also pass various options to configure and annotate the output: 263 264```console 265$ wasmtime objdump foo.cwasm --addresses --bytes --addrma 26600000000 wasm[0]::function[0]: 267 0: fd 7b bf a9 stp x29, x30, [sp, #-0x10]! 268 4: fd 03 00 91 mov x29, sp 269 8: 45 28 40 f9 ldr x5, [x2, #0x50] 270 ╰─╼ addrmap: 0x23 271 c: 86 74 1e 53 lsl w6, w4, #2 272 ╰─╼ addrmap: 0x22 273 10: a2 48 66 b8 ldr w2, [x5, w6, uxtw] 274 ╰─╼ addrmap: 0x23 275 14: fd 7b c1 a8 ldp x29, x30, [sp], #0x10 276 ╰─╼ addrmap: 0x26 277 18: c0 03 5f d6 ret 278``` 279 280# Additional options 281Many of the above subcommands also take additional options. For example, 282- run 283- serve 284- compile 285- explore 286- wast 287 288are all subcommands which can take additional CLI options of the format 289 290```console 291Options: 292 -O, --optimize <KEY[=VAL[,..]]> 293 Optimization and tuning related options for wasm performance, `-O help` to see all 294 295 -C, --codegen <KEY[=VAL[,..]]> 296 Codegen-related configuration options, `-C help` to see all 297 298 -D, --debug <KEY[=VAL[,..]]> 299 Debug-related configuration options, `-D help` to see all 300 301 -W, --wasm <KEY[=VAL[,..]]> 302 Options for configuring semantic execution of WebAssembly, `-W help` to see all 303 304 -S, --wasi <KEY[=VAL[,..]]> 305 Options for configuring WASI and its proposals, `-S help` to see all 306``` 307 308For example, adding `--optimize opt-level=0` to a `wasmtime compile` subcommand 309will turn off most optimizations for the generated code. 310 311## CLI options using TOML file 312Most key-value options that can be provided using the `--optimize`, `--codegen`, 313`--debug`, `--wasm`, and `--wasi` flags can also be provided using a TOML 314file using the `--config <FILE>` cli flag, by putting the key-value inside a TOML 315table with the same name. 316 317For example, with a TOML file like this 318```toml 319[optimize] 320opt-level = 0 321``` 322the command 323```console 324wasmtime compile --config config.toml 325``` 326would be the same as 327```console 328wasmtime compile --optimize opt-level=0 329``` 330assuming the TOML file is called `config.toml`. Of course you can put as many 331key-value pairs as you want in the TOML file. 332 333Options on the CLI take precedent over options specified in a configuration 334file, meaning they're allowed to shadow configuration values in a TOML 335configuration file. 336