CLI Reference

Full reference for the openremap command-line interface. For interactive use, just run openremap with no arguments to launch the TUI.

No server, no database, no internet connection required — install and run anywhere. (Install)

New to the terminal? Run openremap workflow first. It prints a complete plain-English walkthrough with the exact commands to type and what to look for at each step. No reading required.

Know the commands already? Run openremap commands for a one-line-per-command cheat-sheet.

Commands

Every command supports --help for a quick reminder of its arguments and options. Each command has a plain-English intro page, a CLI reference with every flag and example, and (for programmatic use) an API page.

validate strict / validate exists / validate tuned are deprecated aliases for validate before / validate check / validate after. They still work but print a rename notice. Update your scripts when convenient.

Typical session

# New here? Print the full step-by-step guide first
openremap workflow

# Need a quick reminder of all commands?
openremap commands

# Not sure if your ECU is supported?
openremap families
openremap families --family EDC16

# (Optional) Sort a folder of binaries into a tidy library
openremap scan ./my_bins/                    # preview — nothing moves
openremap scan ./my_bins/ --move --organize  # sort into Bosch/EDC17/ etc.

# (Optional) Discover calibration maps in an unsupported or unknown ECU
openremap scan-maps ecu.bin
openremap scan-maps ecu.bin --region 0x10000-0x80000 --min-score 0.85 --show-series

# (Optional) Diff two binaries at map level — which maps changed, by how much
openremap diff-maps stock.bin stage1.bin
openremap diff-maps stock.bin stage1.bin --threshold 5 --json

# 1. Read the stock binary — confirm it is a supported ECU
openremap identify stock.bin

# 2. Health-check it — checksums, axes, map counts, VINs
openremap health stock.bin

# 3. Extract the tune — diff stock vs tuned and save as a recipe
openremap cook stock.bin stage1.bin --output recipe.remap

# 3b. Applying to ANOTHER CAR of the same SW revision?
#     Use cook-volatile — it excludes VIN / checksum-store bytes with evidence
openremap cook-volatile stockA.bin stage1.bin --output portable.remap

# (Optional) Combine small mods — egr_off + stage1 into one recipe
openremap merge egr_off.remap stage1.remap --stock stock.bin -o both.remap

# 4. One-shot: validate before → apply → validate after
openremap tune target.bin recipe.remap

# (Optional) Receipt check — do stock, tuned, and recipe belong together?
openremap audit stock.bin stage1.bin recipe.remap

# If tune fails at Phase 1 — diagnose why
openremap validate check target.bin recipe.remap

# 5. MANDATORY — correct checksums with ECM Titanium, WinOLS, or equivalent
#    before flashing the tuned binary to any vehicle

The old openremap-server daemon (replaced)

⚠ Historical — do not build new integrations on this. The legacy openremap-server daemon has been replaced by the new API transport, and its module (openremap/server.py) no longer exists in the package.

openremap-server used to start a long-running JSON-RPC daemon that non-Python applications (desktop editors, IDE plugins, automation tools written in Rust, Go, C++, Electron, etc.) could use to call the openremap pipeline without cold-starting a Python interpreter on every request.

The replacement is the API transport: the same JSON-RPC calls, served one request per line over stdin/stdout. See API — the programmatic surface and the method reference for what you can call today.

Two things to know if you are porting an old client:

• python -m openremap.server no longer exists — run python -m openremap.api.transport.stdio instead. It stays alive until stdin is closed, exactly like the old daemon.
• The legacy daemon returned bare error strings; the new transport returns JSON-RPC error objects — {"id": <id>, "error": {"code": <int>, "message": "<str>"}} — so clients can branch on the code instead of parsing prose.

Other documentation