# 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: ```console 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: ```console 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`): ```console 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, ```console 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, ```console 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 ```console 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: ```console 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: ```console 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](https://component-model.bytecodealliance.org/design/components.html). The `--invoke` argument is supported to skip calling `wasi:cli/run` and invoke a specific typed export instead. Arguments are passed with [WAVE](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-wave#readme) ,a human-oriented text encoding of Wasm Component Model values. For example: ```console 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: ```console wasmtime run --invoke 'initialize("hello")' foo.wasm ``` And each individual argument within the parentheses is separated by a comma: ```console 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: ```bash 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: ```console wasmtime serve foo.wasm ``` Furthermore, an address can be specified via: ```console 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](https://github.com/sunfishcode/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: ```console 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](./cli-cache.md). You can create a new configuration file for you to edit with: ```console 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: ```console 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: ```console 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: ```console $ 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: ```console $ 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: ```console $ 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 ```console Options: -O, --optimize Optimization and tuning related options for wasm performance, `-O help` to see all -C, --codegen Codegen-related configuration options, `-C help` to see all -D, --debug Debug-related configuration options, `-D help` to see all -W, --wasm Options for configuring semantic execution of WebAssembly, `-W help` to see all -S, --wasi 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 ` cli flag, by putting the key-value inside a TOML table with the same name. For example, with a TOML file like this ```toml [optimize] opt-level = 0 ``` the command ```console wasmtime compile --config config.toml ``` would be the same as ```console 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.