mokxi

Mokxi from a terminal and in CI: compile and simulate Arduino, ESP32 and Pico sketches headlessly, test them with scenarios, keep your circuits in your own git repository and sync them with Mokxi. No dependencies; Node.js 18 or newer.

Simulation tests, free

npx @mokxi/cli run --timeout 10s --expect-serial "Ready" --fail-on "panic"
npx @mokxi/cli test --junit mokxi-junit.xml      # runs mokxi.test.yaml

mokxi run compiles the sketch with the same compiler the Mokxi editor uses and runs it on the same simulator, on your machine or CI runner. No account, no token, no server minutes: the compiler is downloaded once from mokxi.com (about 80 MB) and cached. Free for public and private repos.

It reads a Mokxi project folder, a Wokwi project (diagram.json, wokwi.toml, Wokwi scenario files), a plain Arduino sketch, a .mokxi.json, or a Mokxi or Wokwi project link. A scenario file presses buttons, sets sensors and checks serial output, pins, LEDs and timing:

name: Blink and button
timeout: 10s
fail-on: [panic]
tests:
  - name: blinks at 2 Hz
    steps:
      - wait-serial: Ready
      - expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 }
  - name: the button lights the LED
    steps:
      - press: btn1
      - expect-led: led2
      - set: { part: dht1, temperature: 30.5 }
      - wait-serial: "temp=30.5"
      - screenshot: build/circuit.svg

examples/uno-ci is a whole project with its tests. On GitHub, the mokxiorg/sim-action action runs it (packages/sim-action in this repository). The docs, with the scenario reference and a section on switching from Wokwi CI: https://mokxi.com/docs/ci

Projects in git

npx @mokxi/cli login                      # approve a short code in the browser
npx @mokxi/cli list                       # your projects
npx @mokxi/cli pull <id|link> blink       # the project as files you can commit
cd blink && git init
npx @mokxi/cli push                       # send your edits to Mokxi
npx @mokxi/cli run --timeout 5s           # simulate it here and stream the serial output
npx @mokxi/cli open                       # open it in the browser
npx @mokxi/cli new uno lamp               # start a new project for a board

The files

pull, push and new use the same layout as Save to GitHub in the Mokxi editor and the Mokxi extension for VS Code:

Blink/Blink.ino            the sketch, as an Arduino IDE folder, plus its tabs
diagram.mokxi.json         the whole project (parts, wires, code), so it round-trips
README.md                  with an "Open in Mokxi" badge
.vscode/extensions.json    recommends the Mokxi extension
.vscode/settings.json      which Mokxi project this folder is
.vscode/tasks.json         push, pull, run, compile (arduino-cli) and upload
.gitignore                 .mokxi/ and build/

Edit the sketch folder: when the project is read back it wins over the copy of the code inside diagram.mokxi.json. A plain Arduino sketch folder pushes too; it is given a board (an Uno, or an ESP32 when it includes WiFi).

.mokxi/project.json keeps the sync state. push refuses to overwrite a project that changed on Mokxi since your last pull or push, and pull refuses to replace edits you have not pushed; --force does it anyway.

Commands

mokxi login [--token mkx_... | --paste]   sign in (device login by default)
mokxi logout | whoami
mokxi list [--public] [--board uno]
mokxi new <board> [dir] [--name "..."]
mokxi pull <id|link> [dir] [--force]
mokxi pull                                 inside a pulled folder
mokxi push [dir] [--new] [--force] [--name "..."]
mokxi run [dir|file|link] [--timeout 10s] [--expect-serial TEXT]... [--fail-on TEXT]...
          [--scenario FILE] [--junit FILE] [--firmware [board=]FILE] [--board TYPE]
mokxi test [dir|scenario.yaml] [--junit FILE] [--verbose]
mokxi run --cloud [dir] [--seconds N]           on Mokxi's servers (plan minutes)
mokxi cache [clear]
mokxi open [dir|id]
mokxi upload [dir] --firmware build/Blink/Blink.ino.elf [--board uno1]
mokxi boards
mokxi simulate <id|dir|file|example:slug> ...   assertions, traces, input
mokxi projects ls|get|pull|push                  the API's file-by-file layout
mokxi watch [dir] [--open]                       push on save

mokxi --help has every option. Exit codes: 0 when everything passed, 1 when a run failed (an assertion, a timeout, a --fail-on line, a compile error), 2 for a usage mistake, 3 when the API or a download said no (signed out, a plan limit, a conflict). A plan limit prints the same message the editor shows.

Mokxi's servers do not compile sketches. mokxi run --cloud runs the saved project (with the build the editor keeps after Run) while the folder matches the last sync; with local edits, build with arduino-cli and pass --firmware, or push and press Run in the editor once. Plain mokxi run compiles locally and needs none of that.

The compiler cache is ~/.cache/mokxi (or MOKXI_CACHE_DIR). MOKXI_OFFLINE=1 (or --offline) never touches the network. MOKXI_TOOLCHAIN_DIR and MOKXI_RUNTIME_DIR point at local copies of the compiler and the runtimes (the layout of web/public/toolchain/ and web/public/firmware/runtime/).

The token is stored in ~/.config/mokxi/config.json (or under XDG_CONFIG_HOME) with permissions 0600. MOKXI_TOKEN and MOKXI_API_URL override it.

As a library

import { MokxiClient, toRepoFiles, fromRepoFiles } from 'mokxi';

const mokxi = new MokxiClient({ token: process.env.MOKXI_TOKEN });
const result = await mokxi.simulate({ example: 'uno-blink', duration: '3s' });

Development

Build with npm run build: TypeScript from web/node_modules writes dist/ (committed), and scripts/build-engine.mjs bundles the editor's simulator, importer and compiler (web/src/api-core/headless.ts) into engine/ (built, not committed; npm publish ships it). Test with npm test. The tests run the CLI against a mocked API, run whole simulations on the real engine, and check that dist/ matches src/. The ones that compile need clang.wasm: set MOKXI_TOOLCHAIN_DIR, or run deploy/fetch-toolchain-public.sh clang-v2 from the repository root; without it they are skipped.

Docs: https://mokxi.com/docs/ci, https://mokxi.com/docs/account/cli and https://mokxi.com/developers