Skip to main content

The wasmedge CLI

After installing WasmEdge, you can use the wasmedge CLI to execute WASM files. We will cover how to run WASM files with WasmEdge on your machine and Docker images.

The wasmedge binary is a command line interface (CLI) program that runs WebAssembly programs.

  • If the WebAssembly program contains a main() function, wasmedge would execute it as a standalone program in the command mode.
  • If the WebAssembly program contains one or more exported public functions, wasmedge could invoke individual functions in the reactor mode.

By default, the wasmedge will execute WebAssembly programs in interpreter mode and execute the AOT-compiled .so, .dylib, .dll, or .wasm (universal output format) in AOT mode. If you want to accelerate the WASM execution, we recommend to compile the WebAssembly with the AOT compiler first.

note

The original wasmedgec tool is changed to wasmedge compile. The wasmedge compile CLI tool is the ahead-of-time compiler to compile the WebAssembly file into native code.

$ wasmedge -v
wasmedge version 0.13.4

Users can run the wasmedge -h to realize the command line options quickly or refer to the detailed wasmedge CLI options here. The usage of the wasmedge tool will be:

$ wasmedge -h
USAGE
   wasmedge [OPTIONS] [--] WASM_OR_SO [ARG ...]

...

The wasmedge CLI tool will execute the wasm file in ahead-of-time(AOT) mode or interpreter mode. If the file has been compiled with wasmedge compile, then WasmEdge will execute it in AOT mode, otherwise, WasmEdge will execute it in interpreter mode.

Options​

The options of the wasmedge CLI tool are as follows:

  1. -v|--version: Show the version information. Will ignore other arguments below.
  2. -h|--help: Show the help messages. Will ignore other arguments below.
  3. (Optional) --reactor: Enable the reactor mode.
    • In the reactor mode, wasmedge runs a specified function exported by the WebAssembly program.
    • WasmEdge will execute the function whose name should be given in ARG[0].
    • If an exported function names _initialize, the function will be executed with the empty parameter at first.
  4. (Optional) --dir: Bind directories into WASI virtual filesystem.
    • Use --dir guest_path:host_path to bind the host path into the guest path in WASI virtual system.
  5. (Optional) --env: Assign the environment variables in WASI.
    • Use --env ENV_NAME=VALUE to assign the environment variable.
  6. (Optional) Statistics information:
    • Use --enable-time-measuring to show the execution time.
    • Use --enable-gas-measuring to show the amount of used gas.
    • Use --enable-instruction-count to display the number of executed instructions.
    • Or use --enable-all-statistics to enable all of the statistics options.
  7. (Optional) Resource limitations:
    • Use --time-limit MILLISECOND_TIME to limit the execution time. Default value is 0 which specifies no limitation.
    • Use --gas-limit GAS_LIMIT to limit the execution cost.
    • Use --memory-page-limit PAGE_COUNT to set the limitation of pages(as size of 64 KiB) in every memory instance.
  8. (Optional) WebAssembly proposals:
  9. WASM file (/path/to/wasm/file).
  10. (Optional) ARG command line arguments array.
    • In reactor mode, the first argument will be the function name, and the arguments after ARG[0] will be parameters of wasm function ARG[0].
    • In command mode, the arguments will be the command line arguments of the WASI _start function. They are also known as command line arguments(argv) for a standalone C/C++ program.

TensorFlow Tools​

note

The WasmEdge-tensorflow-tools has been deprecated after the 0.12.1 version and replaced by the plug-ins after the 0.13.0 version.

If users install WasmEdge from the install script with the option -e tf,image, the WasmEdge CLI tools with TensorFlow and TensorFlow-Lite extensions will also be installed.

  • wasmedge-tensorflow CLI tool
    • The wasmedge tool with TensorFlow, TensorFlow-Lite, and wasmedge-image extensions.
    • Only on x86_64 and aarch64 Linux platforms and x86_64 MacOS.
  • wasmedge-tensorflow-lite CLI tool
    • The wasmedge tool with TensorFlow-Lite, and wasmedge-image extensions.
    • Only on x86_64 and aarch64 Linux platforms, Android, and x86_64 MacOS.

Examples​

Build and run a standalone WebAssembly app​

The Hello World example is a standalone Rust application that can be executed by the WasmEdge CLI. Its source code and build instructions are available here.

You will need to have the Rust compiler installed, and then use the following command to build the WASM bytecode file from the Rust source code.

cargo build --target wasm32-wasi --release

You can then use the wasmedge command to run the program.

$ wasmedge target/wasm32-wasi/release/hello.wasm
Hello WasmEdge!

Execute with statistics enabled​

The CLI supports --enable-all-statistics flags for the statistics and gas metering.

You can run:

wasmedge --enable-all-statistics hello.wasm

The output will be:

Hello WasmEdge!
[2021-12-09 16:03:33.261] [info] ====================  Statistics  ====================
[2021-12-09 16:03:33.261] [info]  Total execution time: 268266 ns
[2021-12-09 16:03:33.261] [info]  Wasm instructions execution time: 251610 ns
[2021-12-09 16:03:33.261] [info]  Host functions execution time: 16656 ns
[2021-12-09 16:03:33.261] [info]  Executed wasm instructions count: 20425
[2021-12-09 16:03:33.261] [info]  Gas costs: 20425
[2021-12-09 16:03:33.261] [info]  Instructions per second: 81177218
[2021-12-09 16:03:33.261] [info] =======================   End   ======================

Execute with gas-limit enabled​

The CLI supports --gas-limit flags for controlling the execution costs.

For giving sufficient gas as the example, you can run:

wasmedge --enable-all-statistics --gas-limit 20425 hello.wasm

The output will be:

Hello WasmEdge!
[2021-12-09 16:03:33.261] [info] ====================  Statistics  ====================
[2021-12-09 16:03:33.261] [info]  Total execution time: 268266 ns
[2021-12-09 16:03:33.261] [info]  Wasm instructions execution time: 251610 ns
[2021-12-09 16:03:33.261] [info]  Host functions execution time: 16656 ns
[2021-12-09 16:03:33.261] [info]  Executed wasm instructions count: 20425
[2021-12-09 16:03:33.261] [info]  Gas costs: 20425
[2021-12-09 16:03:33.261] [info]  Instructions per second: 81177218
[2021-12-09 16:03:33.261] [info] =======================   End   ======================

For giving insufficient gas as the example, you can run:

wasmedge --enable-all-statistics --gas-limit 20 hello.wasm

The output will be:

Hello WasmEdge!
[2021-12-23 15:19:06.690] [error] Cost exceeded limit. Force terminate the execution.
[2021-12-23 15:19:06.690] [error]     In instruction: ref.func (0xd2) , Bytecode offset: 0x00000000
[2021-12-23 15:19:06.690] [error]     At AST node: expression
[2021-12-23 15:19:06.690] [error]     At AST node: element segment
[2021-12-23 15:19:06.690] [error]     At AST node: element section
[2021-12-23 15:19:06.690] [error]     At AST node: module
[2021-12-23 15:19:06.690] [info] ====================  Statistics  ====================
[2021-12-23 15:19:06.690] [info]  Total execution time: 0 ns
[2021-12-23 15:19:06.690] [info]  Wasm instructions execution time: 0 ns
[2021-12-23 15:19:06.690] [info]  Host functions execution time: 0 ns
[2021-12-23 15:19:06.690] [info]  Executed wasm instructions count: 21
[2021-12-23 15:19:06.690] [info]  Gas costs: 20

Call a WebAssembly function compiled from Rust​

The add program is written in Rust and contains an exported add() function. You can compile it into WebAssembly and use wasmedge to call the add() function. In this example, you will see how it is done from the CLI. It is often used when you embed WasmEdge into another host application, and need to call a WASM function from the host.

You will need to have the Rust compiler installed, and then use the following command to build the WASM bytecode file from the Rust source code.

cargo build --target wasm32-wasi --release

You can execute wasmedge in reactor mode to invoke the add() function with two i32 integer input parameters.

wasmedge --reactor add.wasm add 2 2

The output will be:

4

Call a WebAssembly function written in WAT​

We created the hand-written fibonacci.wat and used the wat2wasm tool to convert it into the fibonacci.wasm WebAssembly program. It exported a fib() function which takes a single i32 integer as the input parameter. We can execute wasmedge in reactor mode to invoke the exported function.

You can run:

wasmedge --reactor fibonacci.wasm fib 10

The output will be:

89

JavaScript examples​

Using WasmEdge as a high-performance, secure, extensible, easy-to-deploy, and Kubernetes-compliant JavaScript runtime is possible. There is no need to build a JavaScript app. You need to download the WasmEdge JavaScript runtime for Node.js.

wget https://github.com/second-state/wasmedge-quickjs/releases/download/v0.5.0-alpha/wasmedge_quickjs.wasm
wget https://github.com/second-state/wasmedge-quickjs/releases/download/v0.5.0-alpha/modules.zip
unzip modules.zip

Take a simple Javascript file for example. Save the following code as hello.js:

args = args.slice(1);
print('Hello', ...args);

You can run:

wasmedge --dir .:. wasmedge_quickjs.wasm hello.js 1 2 3

The output will be:

Hello 1 2 3

The qjs_tf.wasm is a JavaScript interpreter with WasmEdge Tensorflow extension compiled into WebAssembly. To run qjs_tf.wasm, you must use the wasmedge-tensorflow-lite CLI tool, which is a build of WasmEdge with Tensorflow-Lite extension built-in. You can download a full Tensorflow-based JavaScript example to classify images.

# Download the Tensorflow example
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/aiy_food_V1_labelmap.txt
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/food.jpg
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/lite-model_aiy_vision_classifier_food_V1_1.tflite
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/main.js

$ wasmedge-tensorflow-lite --dir .:. qjs_tf.wasm main.js
label: Hot dog
confidence: 0.8941176470588236

Docker images for the CLI tools​

The Docker images in this section are mostly used for development purposes. They allow you to use WasmEdge tools in containerized Linux environments. If you want to containerize WASM apps, check out this section.

The wasmedge/slim:{version} Docker images provide a slim WasmEdge images built with DockerSlim every releases.

  • Image wasmedge/slim-runtime:{version} includes only WasmEdge runtime with wasmedge command.
  • Image wasmedge/slim:{version} includes the following command line utilities:
    • wasmedge
    • wasmedge compile
  • Image wasmedge/slim-tf:{version} includes the following command line utilities (DEPRECATED after 0.13.0):
    • wasmedge
    • wasmedge compile
    • wasmedge-tensorflow-lite
    • wasmedge-tensorflow
    • show-tflite-tensor
  • The working directory of the release docker image is /app.

Dockerslim Examples​

After pulling the docker image successfully, you could use wasmedge compile and wasmedge to aot compile the wasm file and run the wasm app.

$ docker pull wasmedge/slim:0.13.4

$ docker run -it --rm -v $PWD:/app wasmedge/slim:0.13.4 wasmedge compile hello.wasm hello.aot.wasm
[2022-07-07 08:15:49.154] [info] compile start
[2022-07-07 08:15:49.163] [info] verify start
[2022-07-07 08:15:49.169] [info] optimize start
[2022-07-07 08:15:49.808] [info] codegen start
[2022-07-07 08:15:50.419] [info] output start
[2022-07-07 08:15:50.421] [info] compile done
[2022-07-07 08:15:50.422] [info] output start

$ docker run -it --rm -v $PWD:/app wasmedge/slim:0.13.4 wasmedge hello.aot.wasm world
hello
world

Use wasmedge-tensorflow-lite (link):

note

The WasmEdge-tensorflow-tools has been deprecated after the 0.12.1 version. We'll update to use the WasmEdge plug-in in the future.

$ docker pull wasmedge/slim-tf:0.12.1
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/aiy_food_V1_labelmap.txt
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/food.jpg
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/lite-model_aiy_vision_classifier_food_V1_1.tflite
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/main.js

$ docker run -it --rm -v $PWD:/app wasmedge/slim-tf:0.12.1 wasmedge-tensorflow-lite --dir .:. qjs_tf.wasm main.js
label:
Hot dog
confidence:
0.8941176470588236