chumicro-repl

Host-side serial REPL for CircuitPython and MicroPython boards: line-mode editor, passthrough TUI, programmatic ReplSession, and a tail() follower for deploy orchestration.

Four surfaces, two of them interactive. Line mode is a host-side line editor with persistent per-device history, $EDITOR handoff (:edit), saved snippets (:save / :load / :snippets), and Tab completion against Python keywords plus the board's own namespace. Passthrough mode forwards every keystroke to the board with mpremote-compatible keybindings (Ctrl-C / Ctrl-D / Ctrl-X / Ctrl-E), which is what you want for raw-REPL framing and paste-mode flows. The other two surfaces are for scripts: tail() follows a board for a fixed window and stops on a traceback, and ReplSession runs code on the board and hands back stdout. Every surface decodes UTF-8 safely across chunk boundaries and highlights tracebacks as they scroll past. A pluggable session-failure classifier lets you build your own orchestrator on top.

Part of the ChuMicro family, small focused Python libraries for microcontrollers and laptops. Browse all workbench tools. This is a workbench tool: it runs on your laptop, not on the board.

Install

pip install chumicro-repl

pyserial and prompt_toolkit come along as dependencies. There is no board-side install; chumicro-repl talks to the CircuitPython or MicroPython runtime already on the board over USB serial. Native Windows isn't currently supported (the passthrough TUI needs POSIX termios); WSL2 works.

pip install chumicro-repl-experimental

Quick example

Open an interactive REPL on a board:

chumicro-repl --address /dev/cu.usbmodem1101

On a terminal that drops you into line mode. Type for index in r<Tab> and Tab completes range. Up-arrow recalls history from earlier sessions on the same board. :edit opens $EDITOR with the recent buffer pre-seeded, so a multi-line block isn't a retype. :save my-bringup then :load my-bringup round-trips a snippet you'll paste again tomorrow. Type :help to list every :command.

Need byte-passthrough (paste mode, raw-REPL framing, mpremote-shape Ctrl-C / Ctrl-D)? Add --mode passthrough.

Run something on the board from a script and capture stdout:

from chumicro_deploy import Device
from chumicro_repl import ReplSession

device = Device(transport="micropython", address="/dev/cu.usbmodem1101")

with ReplSession(device) as session:
    output = session.exec("import sys; print(sys.implementation)")
    print(output)  # → "(name='micropython', version=(1,28,0), …)\n"

Follow a board after a deploy and fail the script on a traceback:

from chumicro_repl import tail, ExitCode

result = tail(device, seconds=10)
if result is ExitCode.TRACEBACK_DETECTED:
    raise SystemExit("board crashed during follow-up tail")

What's included

Programmatic API

CLI

chumicro-repl (or python -m chumicro_repl). Opens a serial REPL on a given port.

--mode takes auto, line, or passthrough. The default, auto, picks line mode on a terminal and passthrough when stdin is piped, since line mode needs interactive input.

Line-mode :commands

Type : at the start of a line to invoke a builtin command. :help lists every command live in your session; the seven builtins are:

History is persisted per-device under ~/.chumicro-repl/history/<sanitized-address>/history.txt so a session on back-porch doesn't pollute one on greenhouse. Up-arrow and Ctrl-R reverse search work normally.

Tab completion

Two sources merge:

• Keywords and builtins: print, range, for, import, True, and the rest. Always works, no device round-trip. Covers most "what's that builtin called again" Tab presses.
• On-device dir(): populated on first Tab via a friendly→raw→dir()→friendly round-trip. Cached for the session; :rescan invalidates it after a new import.

The round-trip's friendly-banner reprint is consumed by the fetcher's read-until->>> , so it never leaks into the rendered output. See fetch_device_names() in chumicro_repl.completion if you're embedding the round-trip in your own session shape.

Where this fits

No upstream ChuMicro dependencies; the third-party pyserial and prompt_toolkit do the transport and the line editing. Sister of chumicro-deploy, and used by chumicro-workspace for deploy-and-tail flows.

Companion: chumicro-deploy

chumicro-deploy is the sister workbench tool for pushing code onto a board, probing identity, and flashing firmware. chumicro-repl is narrower, opening a serial REPL given a port path, so the two compose cleanly: Deployer(device).deploy_diff(source) writes the payload, then tail(device, seconds=10) (or any of the API entry points) follows the board for first-cycle output.

Examples

Contributing

Issues, bug reports, and pull requests are welcome, and so is "I ran it on this board and here's what happened", some of the most useful feedback a hardware project can get. Development happens in the ChuMicro repository, whose contributing guide covers setup and the test workflow.

Docs

📖 Stable docs · Experimental docs

Find this library

• PyPI: chumicro-repl
• Source: workbench/repl

License

MIT