moxzi CLI referencealpha

Every moxzi command and option.

moxzi COMMAND --help prints the same information.

Commands#

Options for every command#

build#

Upgrades and metadata#

Metadata names: candid:service, candid:args, motoko:stable-types, motoko:compiler.

Runtime options#

Build performance#

Native kernels#

A native kernel is compiled code that runs inside your canister and shares its memory: it can read and write anything in the canister's heap, and its pin guarantees which bytes run, not that they're correct or benign. The first build that links a kernel moxzi doesn't build and pin itself shows its package, sha256, source and commit, then stops until you accept it. In a terminal, type yes; in CI and scripts, pass --accept-kernel. --yes doesn't accept kernels. Set MOXZI_KERNEL_ACKS to keep the acceptances in another file. See Native kernels.

On-chain builds#

Experimental#

link#

deps#

verify#

publish#

deprecate#

agent-bindings#

host new#

kernel add#

moxzi kernel add PACKAGE opts your application into the native kernel of a package it already depends on. It shows the kernel's package, version, sha256, size, functions, and declared source and commit, checks that the kernel file's bytes match its own sha256, then writes the pin into your mops.toml:

[kernels]
moxzi-hash = "sha256:..."

Only that line changes. If there is no [kernels] table, moxzi appends one, and the rest of the file keeps its formatting. Running it again after the package changes updates the pin. A package without a kernel is refused.

For a third-party kernel (one moxzi doesn't build and pin itself), add also prints what a kernel can do. Adding the pin is not the same as accepting the kernel: the first build that links it still asks you to accept those bytes.

kernel build#

moxzi kernel build CRATE compiles a Rust crate into a native kernel and writes a .kernel.toml file: the wasm in base64, its sha256 and its size. The same crate gives the same bytes on every machine, so anyone can rebuild a kernel and check its pin. Writing a kernel walks through a complete one.

You need rustup with the toolchain nightly-2026-07-25 and its rust-src component. Install them with rustup toolchain install nightly-2026-07-25 --profile minimal --component rust-src. moxzi checks the compiler and its linker by commit. If either is missing or different, the build stops and prints the rustup command that fixes it.

The crate must follow these rules:

Every build runs in /tmp/moxzi-kernel-build, which is deleted first. One build runs at a time. RUSTFLAGS, RUSTC_WRAPPER and the other cargo and rustc settings in your environment are ignored, and each one is named in the output. Cargo configuration files still apply, and each one found is named too.

Write the SDK next to a new crate and generate its lock:

moxzi kernel sdk moxzi-kernel
cargo +nightly-2026-07-25 generate-lockfile --manifest-path reverse-kernel/Cargo.toml

moxzi-kernel: the moxzi-kernel SDK (sources sha256:e055dee34c8e2dd6662fe25e7cb7b7113b648a127122d25a0197d26cc1da3529)
     Locking 1 package to latest compatible version

Build the kernel:

moxzi kernel build reverse-kernel

reverse.kernel.toml: 5633 B, sha256:a0c5237421a2b950e2085d580f53f57dc587db119e4726ecc6f41c5bc40b8e72

kernel verify#

moxzi kernel verify TARGET rebuilds a kernel and compares its bytes with every pin it must equal. It prints MATCH or DIFF for each pin and exits with a non-zero status unless all match. TARGET is one of:

Without --crate, moxzi rebuilds from the package's [kernel] source and commit:

When the package sits in a git checkout of that repository, moxzi uses the checkout, including uncommitted changes, and says so. Otherwise it fetches the commit into a temporary directory. Declare commit in a published package. A branch name moves, and moxzi prints a note when it checks one.

moxzi kernel verify reverse.kernel.toml --crate reverse-kernel

  MATCH reverse.kernel.toml: sha256:a0c5237421a2b950e2085d580f53f57dc587db119e4726ecc6f41c5bc40b8e72
  MATCH reverse: rebuilt sha256:a0c5237421a2b950e2085d580f53f57dc587db119e4726ecc6f41c5bc40b8e72 (5633 B)
kernel verify: every pin MATCHES the rebuilt bytes

kernel sdk#

moxzi kernel sdk DIR writes the moxzi-kernel SDK that this moxzi builds with. Cargo needs it on disk to generate Cargo.lock, and your editor needs it to check the crate.

Environment variables#

Removed options#

--legacy-actors, --no-eop and --trap-on-call-error are no longer supported and print an error. --default-persistent-actors is ignored with a warning: every actor is persistent.