CLI
The kog CLI is installed per-project (npx kog … or via package scripts). Everything is Node — no external tools.
Every command accepts --help (-h) and prints its usage without doing anything else — kog flash --help shows the options, it never touches your board. On macOS, --port accepts either the /dev/cu.* or the /dev/tty.* name for a device; they refer to the same port.
Commands
kog dev
Dev server + hot reload. Compiles on save and pushes to every target — the simulator and, when a blessed board is plugged in over USB, the board itself (bundle compiled to QuickJS bytecode and hot-reloaded over the serial dev-link). Streams the board's console.* and errors back to your terminal. A plugged-in board is targeted by default.
Hot reload to a board is over USB serial only — there is no Wi-Fi/network hot-reload path. (Wi-Fi on the device is for your app's own networking; it isn't a code-push channel.) Hot reload works on a board that's in development posture — the state a kog flash leaves it in; a kog deployed board has hot reload off (see below).
To attach, kog dev pulses a reset on the board so it re-announces itself (a board sends its dev-link handshake once at boot); you'll see a Board linked … line once the ABI check passes. If no board is found it runs the simulator alone.
--sim — simulator only (don't target a board) · --port <p> — use a specific serial port · --no-sim — skip the simulator (device + dev server only) · --headless — run the simulator without a window
kog build
Type-check (tsc --noEmit, fails on type errors) → compile → bundle → bytecode. Outputs a deployable signed bundle.
--release — optimizations on, console stripped.
kog flash
First-time or full flash over USB: detects the board, resolves the matching prebuilt runtime image (each part SHA-256-verified before writing), and writes the bootloader, partition table, runtime, and board configuration in one pass. Pure Node — no Python, no esptool install. The flash baud is chosen per USB bridge automatically (native-USB boards run fast; UART bridges like the CYD's CH340 drop to a safe rate). Leaves the board in development posture — the dev-link is reserved so kog dev can hot-reload it.
--port <p> — explicit serial port (otherwise auto-detected) · --board <id> — pick a board when chip detection is ambiguous (cyd | cyd-classic | waveshare-1.46b) · --baud <n> — override the auto-selected flash baud · --manifest <path|url> — use a specific boards.json instead of the bundled one
The CYD needs --board: its two panel generations share one silkscreen and one chip id, so the CLI won't guess. Flash --board cyd first; a left/right-mirrored screen with orange-instead-of-blue UI means yours is the classic generation — reflash with --board cyd-classic. See Flash your board.
kog deploy
Build and install the app bundle onto a connected board as its standalone app — the signed OTA path. The bundle is staged to flash and committed with a rollback-pending flag that clears once the board boots it healthy, so a bundle that fails to boot rolls back to the last-good image. Survives power-cycles, unlike kog dev's RAM hot-reload. Uses the same USB port discovery as kog flash.
Puts the board in production posture: hot reload is turned off and the full RAM goes to your app — a deployed board has no code-push channel (the dev-link isn't reserved). To go back to developing on that board, run kog flash again.
By default the bundle is unsigned — a development board (keyless, the state kog flash leaves it in) accepts it (spec/05 §2). It's signed only when you configure a key: ota.signingKey in kog.config, KOG_SIGNING_KEY, or --signing-key — the production path, where the board is provisioned with the matching public key.
After staging, the board is reset so it boots the deployed app immediately (OTA install itself doesn't reboot). Pass --no-reset to leave the running app in place; it boots the new bundle on the next manual reset.
--port <p> — explicit serial port · --signing-key <path> — sign with a specific Ed25519 key (overrides kog.config ota.signingKey) · --unsigned — force an unsigned bundle even if a signing key is configured · --no-reset — stage without resetting the board
kog flash/kog deploy device behavior is confirmed against live hardware in the hardware-validation pass; flag details here track the shipped commands.
kog simulate
Launch the simulator without the dev server (runs the last built bundle).
kog doctor
Environment check: Node version, serial access, simulator binary, board detection — every failure paired with its fix.
kog board validate
Validate board.yaml against the schema; explains any mismatch.
kog firmware build
Compile a custom runtime from board.yaml (Tier C). First run bootstraps the managed toolchain automatically. See Boards.
kog wifi
Provision Wi-Fi credentials over a USB-connected device.
create-kog
Project scaffolding — invoked as npm create kog@latest [name].