kube32-cli

kube32-cli [--version] command [options]kube32-cli build dir [options]kube32-cli check file [--memory qty]kube32-cli deploy file [options]kube32-cli embed file [options]kube32-cli sd-push file (--to mount | --node node) [options]kube32-cli push file-or-dir --node node [--path path]kube32-cli firmware push|rollout|status|abort|info [options]

kube32-cli is a Python 3 (standard library only) tool that lives at `tools/kube32-cli` in the Kube32 tree. It compiles application directories to WebAssembly, checks modules against the Kube32 app ABI header and the wasm3 import table, and ships them to a cluster that kube32-sim or ESP32-S3 boards are running.check requires known host imports (k32 app calls and esp32 peripheral calls) and one of two export styles: a request-handler set (k32 init, alloc, handle, tick, event) or an entry point (start, app main, or main). Hardware capabilities (`display`, `keyboard`, `speaker`, `ipc`, `sd`, `service-call`) are inferred from those imports unless --hardware is set.deploy, push, sd-push --node, and firmware drive the API server through kubectl (kubeconfig credentials apply). build shells out to Clang, rustc/wasm-ld, or the AssemblyScript compiler depending on --lang.Exit codes: 0 success, 1 input or toolchain error, 2 usage, 3 ABI check failed, 4 kubectl failed, 5 pod already exists during deploy (pass --replace) or a firmware rollout is already in progress, 6 firmware rollout failed or timed out.

--version

Print `kube32-cli` and the package version (currently 0.2.0) and exit.

Compile a C, Rust, or AssemblyScript directory to `.wasm` and run check. --lang `c` | `c-make` | `rust` | `assemblyscript` overrides detection. --name sets the module name. -o / --out is the output path (default `<dir>/build/<name>.wasm`). --memory (default 64Ki) is linear memory, initial = maximum, a multiple of 64Ki (ignored for Makefile projects). --stack (default 16Ki) is the C/Rust shadow stack. --target (default `wasm32-unknown-unknown`) is the Rust target. -v prints compiler commands.

Validate a `.wasm` against the app ABI and this runtime's wasm3 opcode set. --memory qty fails when the module declares more linear memory than that.

Create a Pod via `kubectl create`, carrying the module in the `kube32.io/wasm-base64` annotation unless --image is set. --name defaults to the file stem. --node pins `spec.nodeSelector`. --namespace defaults to default. --memory (default 64Ki) is the resources memory request and limit. --psram is the `esp32.io/psram` request; the Wasm sandbox is max(memory, psram). --hardware is a comma list of `ipc`, `display`, `keyboard`, `speaker`, `sd`, or `none` (default: inferred from imports). --sd-claim is the volume claim for `sd` (default: the pod name). --env `K=V` is repeatable. --image uses a `wasm://sd/<name>` or `wasm://embedded/<name>:v1` reference instead of inline bytes. --port (default 7000) is the container port. --replace deletes an existing pod of that name first. --timeout (default 60) is how long --replace waits for the old pod to go away. --dry-run prints the manifest. --context, --kubeconfig, --server, --kubectl select the kubectl binary and cluster.

Copy a checked module to `images/<name>.wasm` for `wasm://embedded/<name>:v1`. --force overwrites. --images-dir overrides the repo `images/` directory.

Copy a checked module to `kube32/images/<name>[-<tag>].wasm` as `wasm://sd/<name>[:<tag>]`. --to is a local mount point; --node ships over the network instead. --name and --tag set the image name and tag. Accepts the same kubectl flags as deploy.

Upload a file or directory tree to `<storage-root>/kube32/<path>` through `kubectl replace --raw` on the node's storage proxy. Default --path is `images/<filename>` for a file, or `images` for a directory. Prints one line per file, stops at the first error, and exits 1 if a directory is empty.

Check that the image's last 32 bytes are its SHA-256, then upload it into the control plane's update slot in ranges (resumes an interrupted upload). Does nothing when the image is already staged. --chunk (default 16Ki) is bytes per request. --retries (default 5) is consecutive failures before giving up.

Create the `FirmwareRollout` named `firmware` for the staged image and print progress until it completes or fails. Workers update one at a time, then the control plane. --sha256 refuses unless it matches the staged image. --node-timeout (default 900) is seconds a node has to switch and confirm. --no-wait starts the rollout and returns. --timeout (default 3600) and --interval (default 5) control the wait loop.

Print the staged image, the rollout, and a node table (version, image, slot, confirmation, target, FirmwareUpdate condition).

Delete the rollout. Nodes that have not switched keep their running firmware.

Print the version and SHA-256 of an image file.

The script expects to run from a Kube32 checkout: build and embed locate the repo root next to `tools/`. It is not a separately packaged binary.deploy without --replace exits 5 when the pod name already exists. firmware rollout does the same when a rollout is already running.SD images are size-capped (256Ki without PSRAM, 2Mi with PSRAM). check does not execute the module.

kube32-sim(1), kubectl(1), cmake(1), pio(1), clang(1), cargo(1), wasm-objdump(1), esptool(1)

Source code · Documentation