cyberboard-cli

A CLI — and the protocol knowledge base behind it — for writing AngryMiao CyberBoard R4 configuration without the official AM Master app.

The goal: manage your keymap and LED display as separate, version-controllable sources, and write them straight to the board from the command line — robustly, without AM Master's flaky connection.

Status: the write protocol is fully reverse-engineered, and the cyberboard CLI is implemented and published (see Install below). Writing and keymap read-back are verified on real R4 hardware; keymap authoring (TOML) and LED display authoring (GIF / declarative recipes) work today, and the MCP server and Claude Code plugin ship alongside the CLI. Still WIP: per-key LED authoring. The self-contained protocol spec lives under .claude/rules/ (Japanese).

Install

Prerequisite: Python ≥ 3.11. Every method below installs the same package (cyberboard-cli on PyPI) — they differ only in how it lands on your machine.

Which installer should I pick?

Pick your extras

The package is a small core plus opt-in extras, so a device-only or keymap-only setup stays lean. Add them in brackets, e.g. 'cyberboard-cli[led,verify]':

Commands

# Homebrew (macOS) — full app (device I/O + LED + keymap edit), completion auto-wired:
brew install GeneralD/tap/cyberboard-cli

# uv tool — isolated global command (recommended for the full feature set):
uv tool install cyberboard-cli                 # core only
uv tool install 'cyberboard-cli[led]'          # + LED authoring

# pipx — isolated global command:
pipx install 'cyberboard-cli[led]'

# pip — into the currently-active venv:
pip install 'cyberboard-cli[led]'

# uvx — run once, nothing installed:
uvx --from 'cyberboard-cli[led]' cyberboard --help

Homebrew bundles the full app — device I/O, LED authoring (anim / led / compose), and the keymap editor (keymap edit). pillow ships as a prebuilt wheel and textual is pure Python, so installs stay quick (~30 s, not a long source build). Only the [verify] and [mcp] extras aren't bundled (both degrade gracefully). If you want them, install a separate uv tool install 'cyberboard-cli[all]' — use [all] (not just [verify,mcp]) so that environment can also render LED when it runs the MCP server.

Developing on a clone? Run it straight from the source tree, no install:

uv run --extra led cyberboard --help   # device commands don't need --extra led

Usage

cyberboard <command> — run cyberboard <command> --help for each command's options.

cyberboard devices                                              # find your board
cyberboard anim preview -r examples/led/text-scroll.json -o preview.gif   # author an LED animation
cyberboard led play -i preview.gif                              # play it right in the terminal (Ctrl-C to stop)
cyberboard compose -m examples/led/compose.toml -b base.json -o config.json   # combine many sources per slot
cyberboard build -k keymap.toml -b base.json -o config.json     # build a config from a TOML keymap
cyberboard keymap show config.json --layer 1                    # view the keymap (colored grid; --color auto/always/never)
cyberboard keymap edit config.json                              # edit it interactively — click a key to reassign (needs [tui])
cyberboard write config.json --execute                          # write it (omit --execute for a dry run)

Shell completion

cyberboard completion <shell> prints a completion script. Homebrew wires this up automatically; for a pip/uv install, install it manually:

cyberboard completion zsh  > "${fpath[1]}/_cyberboard"            # zsh (then restart)
cyberboard completion bash > /usr/local/etc/bash_completion.d/cyberboard   # bash
cyberboard completion fish > ~/.config/fish/completions/cyberboard.fish    # fish

MCP server

Every CLI operation is also exposed to MCP clients (Claude Desktop, Claude Code, editors, AI agents) through a small stdio server that simply wraps the CLI — so the MCP tool surface never drifts from the CLI's behaviour.

1. Install with the [mcp] extra so the cyberboard-mcp command is on your PATH (add [led] too if you want the LED tools to render inside the server):

uv tool install 'cyberboard-cli[mcp]'        # or: pipx install / pip install
uv tool install 'cyberboard-cli[mcp,led]'    # + LED tools (render/preview/gif)
cyberboard-mcp                               # quick check: serves over stdio (Ctrl-C to quit)

2. Register it with your client — the command must be on the client's PATH:

{ "mcpServers": { "cyberboard": { "command": "cyberboard-mcp" } } }

Per client:

• Claude Code — just use the plugin below; it wires the server for you, no JSON editing.

• Claude Desktop / Cursor / editors — paste the JSON above into the client's MCP config. If it can't find the command, give an absolute path (which cyberboard-mcp) or run it through uvx (no separate install needed):

  { "mcpServers": { "cyberboard": {
      "command": "uvx",
      "args": ["--from", "cyberboard-cli[mcp]", "--with", "mcp<2", "cyberboard-mcp"] } } }
  

• mcpm users — register it once and add it to a profile:

  mcpm new cyberboard --type stdio --command uvx \
    --args "--from cyberboard-cli[mcp] --with mcp<2 cyberboard-mcp"
  mcpm profile edit base --add-server cyberboard
  

Tools (11): list_devices · device_info · doctor · verify · build_keymap · render_animation · preview_animation · gif_to_ir · ir_to_gif · read_keymap · write_config.

write_config is destructive and defaults to a dry run — pass execute=true to actually write to the board. The LED tools (render_animation / preview_animation / gif_to_ir / ir_to_gif) need the [led] extra in the same environment.

Claude Code plugin

For Claude Code, the plugin auto-configures the cyberboard MCP server — no hand-editing of mcpServers, and no separate package install needed.

Inside Claude Code (these are slash commands, not shell), add this repo as a plugin marketplace and install the plugin:

/plugin marketplace add GeneralD/cyberboard-cli
/plugin install cyberboard@cyberboard-cli

Enabling it starts the server automatically. The MCP entry self-bootstraps via uvx --from 'cyberboard-cli[mcp,led]' --with 'mcp<2' cyberboard-mcp — uvx fetches the package on first launch (LED tools included, pillow from a wheel — no source build) and caches it thereafter.

Prerequisite: uv (for uvx). Nothing else to install — the plugin pulls the server itself. The plugin manifest lives at plugins/cyberboard/ and the marketplace manifest at .claude-plugin/marketplace.json (both in this repo).

Why

The official setup has three problems this project fixes:

• Keymap and LED live in one JSON file. Applying a community LED animation overwrites your keymap. This project keeps them apart and recombines them only at build time, so "swap just the LED" is safe.
• AM Master's connection is flaky — writes succeed or fail at random. The root causes are now identified (see the protocol doc) and are fixable on the CLI side.
• It's inflexible — no partial updates, no scripting, no diffing.

What we know (headline findings)

All reverse-engineered from AM Master 1.3.7 (decompiled locally; the decompiled sources are not redistributed here — see Legal):

• Transport is USB CDC serial (pyserial) @ 9600 baud. HID is detection-only.
• No encryption on the config path — the AES in the app is just PyInstaller bytecode obfuscation.
• Frames are a fixed 64 bytes: [0] category, [1] subcommand, [2..62] payload, [63] CRC-8 (poly 0x07).
• LED model: frames = the 40×5 = 200-px top display; keyframes = the 90 per-key backlights. Slots 1/2/3 = pages 5/6/7. (Empirically verified: active pages always pack to exactly 200 px / 90 px — see verify_encoding.py in the research wiki.)
• Send sequence and full command table are documented in .claude/rules/30-write-protocol.md.

Repository layout

Confidence is marked throughout: 🟢 source-confirmed · 🟡 strong inference · 🔴 needs live-hardware capture.

Roadmap

Done:

• M0 — Protocol analysis ✅ decompiled; encoding verified; wire bytes confirmed by live serial handshake on a real R4.
• M1 — Full write ✅ a known-good config writes over the reverse-engineered sequence (LED visually confirmed on hardware).
• M2 — Read-back + diff ✅ for the keymap (write → read → 1400/1400 match). LED has no read-back path, so it's authored from source.
• M3 — Keymap build ✅ keymap.toml → IR with lossless round-trip.
• M5 — LED display authoring ✅ GIF ⇄ IR codec + declarative animation recipes
  • an in-terminal player (led play, half-block truecolor) and a frame montage (anim montage) for judging motion/loop in a still viewer.

Productization ✅ a unified cyberboard CLI core, standalone packaging (published to PyPI + a Homebrew tap), an MCP server (cyberboard-mcp), and a Claude Code plugin — all calling the same core. Next: per-key LED authoring and a sprite/vision LED design loop.

Note: partial writes are not supported by firmware (JSON_START erases the whole config), so "swap just the LED" is done by read → merge → full write, not by a partial write.

Legal

This is an independent interoperability project. The reverse-engineering was done on a locally-owned copy of AM Master for the sole purpose of interoperating with hardware the author owns. The vendor's app, its installer, its extracted bytecode, and the decompiled sources are deliberately excluded from this repo (see .gitignore); only original analysis and first-party tooling are published. All trademarks belong to their respective owners. "AngryMiao" and "CyberBoard" are trademarks of AngryMiao.

Acknowledgements

• angrymiao-cyberboard-config-merger and miaomerge — sibling tools that merge/composite LED animations into a writable JSON (writing still relies on AM Master; that's the gap this project closes).