opman CLI User Guide
Documentation for @zenovate/opman 0.1.10. Confirm your install with
opman --version. For full flags, useopman <command> --help.
opman is the command-line tool for OP devices. It compiles Python to PikaPython bytecode (.py.o), uploads over serial or BLE, deploys and runs scripts, and provides a Python REPL and BLE scan.
For tool selection and field upload with OP Manager, see the OP-BTS Python Script Usage Guide & Tool Reference.
Contents
Platform support
| Platform | Support |
|---|---|
| macOS (arm64 / x64) | Yes |
| Windows x64 | Yes |
| Linux | Not supported (npm package does not ship Linux binaries) |
| Windows ARM (native) | Not claimed; use Windows x64 |
Install
Prerequisite: Node.js ≥ 16 (includes npm).
Global install:
npm install -g @zenovate/opman
opman --version
Project-local:
npm install -D @zenovate/opman
npx opman --help
Examples below use the opman command (global install). With a project-local install, prefix with npx.
Quick start
Replace COM3 with your serial port (Windows) or a /dev/cu.* path (macOS). Many optical docks use 9600 baud; opman’s default baud is 115200 when you omit -b.
# 1) Compile .py → .py.o (no device needed)
opman compile hello.py
# 2a) Upload only (no run)
opman upload hello.py.o /py -p COM3 -b 9600
# 2b) Or compile + upload + run in one step
opman deploy hello.py -p COM3 -b 9600
# Optional: Python REPL on the device
opman python -p COM3 -b 9600
BLE (prefer a smaller --packet-size on macOS):
opman ble-scan --name OP
opman deploy hello.py --ble ZENO --packet-size 50
Scripts on the device must live under /py.
Command reference
Need a connection? Use -p (serial) or --ble (BLE)—one is required; they are mutually exclusive.
compile
Compile .py to .py.o locally (no device).
opman compile hello.py
opman compile *.py -o build/
opman compile hello.py -o build/hello.py.o
| Flag | Default | Description |
|---|---|---|
-o / --output |
Same directory as each input | Output .py.o file or directory |
upload
Upload a local file to a device directory (does not run the script).
opman upload hello.py.o /py -p COM3 -b 9600
opman upload hello.py.o /py --ble AA:BB:CC:DD:EE:FF --packet-size 50
| Flag | Default | Description |
|---|---|---|
-p / --port |
— | Serial port (e.g. COM3, /dev/cu.usbserial-xxx) |
--ble |
— | BLE address or name (partial match) |
-b / --baud |
115200 |
Serial baud (ignored if -c is set) |
-c / --serial-config |
— | Full serial settings, e.g. 9600,N,8,1 |
--remote-name |
Local filename | Filename on device |
--packet-size |
100 |
Upload chunk size (bytes) |
--skip-command-mode |
off | Skip entering command mode before upload |
deploy
Compile (if input is .py), upload to the device (default /py), then run PythonFileRun. Use upload if you only want to transfer.
| Input | Behavior |
|---|---|
.py |
Compile → upload → run |
.py.o / *.o |
Skip compile; upload → run |
opman deploy hello.py -p COM3 -b 9600
opman deploy hello.py.o -p COM3 -b 9600
opman deploy hello.py -p COM3 -b 9600 --monitor
opman deploy hello.py --ble ZENO --packet-size 50 --monitor
| Flag | Default | Description |
|---|---|---|
--remote-dir |
/py |
Device directory |
-o / --output |
Same dir as input | Local .py.o when compiling .py |
--remote-name |
From input | Filename on device (used for run) |
--monitor |
off | After run, print raw output until ESC |
--run-timeout |
30 |
Seconds to wait for PythonFileRun |
--hex / --timestamp |
off | Monitor display options |
--packet-size |
100 |
Upload chunk size (bytes) |
-p / --ble / -b / -c |
— | Same as upload |
shell
Interactive command mode (device parameters / JSON commands). Prompt: >.
opman shell -p COM3 -b 9600
opman shell --ble ZENO
| Flag | Default | Description |
|---|---|---|
--timeout |
5 |
Response timeout per command (seconds) |
--skip-command-mode |
off | Skip command-mode entry |
python
Interactive Python REPL on the device. Prompt: >>>. opman enters Python mode automatically.
opman python -p COM3 -b 9600
opman python --ble ZENO
On the device, use exit() to leave the REPL. Locally, quit disconnects only.
| Flag | Default | Description |
|---|---|---|
--timeout |
30 |
Timeout per Python line (seconds) |
--skip-python-mode |
off | Device already in REPL |
--no-legacy-fallback |
off | Do not fall back on older firmware path |
ble-scan
Scan for BLE devices (no serial port needed).
opman ble-scan
opman ble-scan --name OP
opman ble-scan --all-devices
| Flag | Default | Description |
|---|---|---|
--name |
— | Filter by name substring (case-insensitive) |
--all-devices |
off | Do not filter by name keywords |
--timeout |
15 |
Scan duration (seconds) |
monitor
Print raw serial or BLE data. Press ESC (or Ctrl+C) to stop.
opman monitor -p COM3
opman monitor -p COM3 --hex --timestamp -o capture.log
opman monitor --ble ZENO --hex
| Flag | Default | Description |
|---|---|---|
--hex / --timestamp |
off | Display options |
--no-drain |
off | Keep serial buffer after connect (serial only) |
-o / --output |
— | Also write to a file |
completion
Generate shell completion scripts (bash / zsh / fish / powershell).
opman completion bash
opman completion zsh
opman completion fish
opman completion powershell
Current session examples:
| Shell | Command |
|---|---|
| Bash | source <(opman completion bash) |
| Zsh | source <(opman completion zsh) |
| Fish | opman completion fish | source |
| PowerShell | opman completion powershell | Out-String | Invoke-Expression |
Serial ports and BLE devices are not auto-suggested; set -p or --ble yourself.
Connection tips
Serial
- Only one program may open the port at a time (close other serial tools first).
- Optical dock setups often use COM3 @ 9600 8N1 on Windows—pass
-b 9600(opman default is 115200). - macOS paths look like
/dev/cu.usbserial-…(prefercu.*overtty.*for outgoing). - Full settings:
-c "9600,N,8,1"(parityN/E/O, data bits7/8, stop bits1/2).
BLE
- On macOS, allow Bluetooth for your terminal under System Settings → Privacy & Security → Bluetooth.
--bleaccepts an address/UUID or a name (partial match; first match after ~15 s scan).- Prefer
opman ble-scanfirst; do not share the link with OP Manager at the same time. - macOS + BLE upload: default
--packet-sizeis100. If you seeFileWrite timed out repeatedly, use--packet-size 50(or30). Serial uploads usually do not need this.
FAQ
How do I find the serial port?
- Windows: Device Manager → Ports (COM & LPT), note
COMx. - macOS:
ls /dev/cu.*after plugging in the adapter; pick the matchingcu.usbserial-…(or similar).
opman does not list ports for you.
macOS BLE upload fails with FileWrite timed out
Use a smaller chunk size, for example:
opman upload hello.py.o /py --ble ZENO --packet-size 50
npm install fails / I am on Linux
- Confirm Node.js ≥ 16 and that you are on macOS or Windows x64.
- Linux is not supported by the published npm package. There is no supported install path on this site for Linux.
What is the difference between deploy and upload?
upload: transfers the file only.deploy: optionally compiles.py, uploads, then runs the script on the device (PythonFileRun).
Where must scripts live on the device?
Under /py. Scripts outside /py will not run correctly.
Windows serial driver or permission issues
Install the matching USB–serial driver for your dock/adapter from the Technical Support driver download section (CH34x / FTDI as applicable). Run the terminal with permission to access the COM port, and close other apps using that port.