The mokxi command line

Keep a project in a folder of your own, sync it with Mokxi, and run it from a terminal.

mokxi is a small command line tool with no other dependencies. It needs Node.js 18 or newer. Run it with npx @mokxi/cli, or install it once with npm install -g @mokxi/cli.

npx @mokxi/cli login

It shows a short code and opens mokxi.com/device. Approve it there, and the tool gets a token of its own. To paste a token you made under Settings > Developer instead, run npx @mokxi/cli login --paste.

The token is saved in your user's config folder (~/.config/mokxi/config.json, or under XDG_CONFIG_HOME), readable only by you. npx @mokxi/cli logout forgets it; revoke it under Settings > Developer when you are done with it.

Commands

Command	What it does
`mokxi list`	your projects, with their ids
`mokxi new <board> [dir]`	starts a project for a board, such as `mokxi new uno blink`
`mokxi pull <id or link> [dir]`	writes the project as files (see below)
`mokxi pull`	inside a pulled folder: gets the latest
`mokxi push [dir]`	sends the folder to Mokxi, making the project the first time
`mokxi run [dir] [--seconds N]`	runs it on Mokxi and prints the serial output as it comes
`mokxi open [dir or id]`	opens the project in your browser
`mokxi upload [dir] --firmware FILE`	stores a build (an arduino-cli `.elf`) with the project
`mokxi boards`	the boards Mokxi simulates

mokxi --help lists every option.

The files

mokxi pull writes the same layout as Save to GitHub in the editor: the sketch as an Arduino IDE folder (Blink/Blink.ino and its tabs), the whole project as diagram.mokxi.json, a README with an Open in Mokxi badge, and .vscode/ settings and tasks. See Mokxi, VS Code and GitHub for what each file is.

So a typical start is:

npx @mokxi/cli pull https://mokxi.com/p/abc123 blink
cd blink
git init && git add . && git commit -m "From Mokxi"

Then edit, npx @mokxi/cli push, and commit as you would any code. A clone of the repository finds its project in .vscode/settings.json, so mokxi push works there too.

Safe syncing

.mokxi/project.json remembers what was last synced (it is in .gitignore).

mokxi push refuses when the project changed on Mokxi since your last pull or push, so it never overwrites work done in the browser. --force overwrites anyway.
mokxi pull refuses when you changed files you have not pushed yet. --force replaces them.
A tab deleted on Mokxi is deleted from the folder on the next pull, unless you changed that file.

mokxi push --new makes a new project from the folder instead of updating the one it came from.

Running

mokxi run uses the API's simulator and counts against your plan's API minutes. While the folder matches what was last synced it runs the saved project, including the build the editor keeps after you press Run. With local changes it sends the folder's files, and Mokxi's servers do not compile: build with arduino-cli and pass --firmware build/Blink/Blink.ino.elf, or push and press Run in the editor once. run takes the same checks as mokxi simulate, such as --expect-serial ready, and exits with 1 when one fails, which is what a CI job wants.

Plan limits

Pushing a new project counts against your plan's project limit like any other project. When you are at it, mokxi push prints the same message the editor shows, and exits with 3.

Exit codes

0 when everything worked, 1 when a run failed a check, 2 for a mistake in the command, and 3 when Mokxi said no (signed out, a plan limit, a conflict).