Command-line tools

On Windows use python where this page says python3.

CP Tools (cptools)

cptools is a shim for python3 tools/app_manager.py, run in a platform-idf checkout. With no arguments it opens the interactive manager (TUI).

command	options	what it does
list	--all, --json	List available and installed apps (--all adds incompatible ones)
install APP	--ref, --origin, --force	Install an app as a submodule under components/ (--ref defaults to main)
remove APP	none	Remove an installed app
update [APP]	--all, --force, --dry-run	Update one app or all; --force backs up local work first
status [APP]	--json	Track policy vs actual git state, all apps or one
track APP MODE	--ref, --commit, --local	Set what an app follows: release, development, version or mine (old names still work)
backup APP	none	Snapshot an app’s local work into .crosspad/backups/
restore APP [STAMP]	--list	Restore a backup (newest by default), or list them
new APP_ID	--name, --description, --category, --private/--public, --owner, --no-install	Scaffold an app from the template; --private/--public also creates and pushes its GitHub repo
device	--json	Diff what the connected CrossPad was built from against this checkout; exit 2 when they differ
config-init	none	Create crosspad.config.json from the current state
config [FLAG] [VALUE]	--local, --gen	Show or set compile-time feature flags (on/off or an enum value)
profile ACTION [NAME]	--remove-extra, --description	Named build recipes: list, show, apply, save
sync	none	Sync the manifest with the app submodules already on disk
tui	--plain	Interactive terminal UI; --plain drops colour and full-screen redraw (screen readers)
doctor	--json	Check tools, board, network and project folder, with a fix for each; exit 1 if anything is wrong
support	none	Save a zip with logs and findings to send to support
update-board	none	The “Update my CrossPad” flow without a screen: download, build, flash, check

track modes: development takes --ref (a branch), version takes --commit. The old names registry, branch, pinned and local still work. --local on track and config writes to crosspad.local.json; config --gen regenerates .crosspad/build_flags.*. new --category is music, audio, tools or other. profile apply --remove-extra removes apps the profile omits.

cptools list --all
cptools install sampler
cptools update --all --dry-run
cptools track sampler development --ref main
cptools restore sampler --list
cptools new my-app --name "My App"
cptools profile apply NAME
cptools tui --plain

More: Install and remove apps, Start from the template.

idf.py CrossPad extensions

Run idf.py in the platform-idf root (the crosspad-idf shim does that for you). Every build or flash command needs -B build_v2 -DSDKCONFIG=sdkconfig.v2 (build_v1 / sdkconfig.v1 for a r16 / r19 board). The actions below come from idf_ext.py and mirror CP Tools.

action	options	what it does
app-list	--all	List available and installed apps (--all includes incompatible ones)
app-install	--app, --ref, --origin, --force	Install an app as a git submodule in components/ (--ref defaults to main)
app-remove	--app	Remove an app submodule
app-update	--app, --all, --force, --dry-run	Update one or all installed apps; --force backs up local work first
app-sync	none	Sync the manifest with existing app submodules
app-manage	none	Open the interactive app manager (TUI)
app-status	--app	Track policy vs actual git state, all apps or one
app-track	--app, --mode, --ref, --commit, --local	Set what an app follows: --mode release | development | version | mine; --ref for development, --commit for version
app-backup	--app	Snapshot an app’s local work into .crosspad/backups/
app-restore	--app, --stamp, --list	Restore a backup (newest unless --stamp), or list them
app-config	--flag, --value, --local, --gen	Show or set compile-time feature flags
app-profile	--profile-action, --name, --remove-extra, --description	Named build recipes: list (default), show, apply, save
app-device	none	Ask the connected device what it was built from and diff against this checkout
app-new	--app, --name, --description, --category, --private, --public, --owner	Scaffold a new app from the template, optionally creating its GitHub repo
board	--set, --board, --device	Show the board revision that builds and flashes use; --set v1|v2 remembers one

idf.py app-install --app sampler
idf.py -B build_v2 -DSDKCONFIG=sdkconfig.v2 build

Installer shims

Only present if you installed with the one-liner. On Linux and macOS they live in the project’s bin/ and are linked into ~/.local/bin; on Windows they are .cmd files in C:\CrossPad\firmware\bin, which is on your user PATH. Each one except crosspad-sim sets up ESP-IDF before it runs, so no export.sh is needed.

command	runs	present when
cptools	tools/app_manager.py	always
crosspad-idf	idf.py, from the project folder	always
crosspad-flash	tools/ota_flash.py	always
crosspad-files	tools/fs_transfer.py	always
crosspad-board	tools/crosspad_board.py	always
crosspad-bench	tools/bench.py	always
crosspad-hil	crosspad-hil from the project’s .venv	crosspad-hil is installed in .venv
crosspad-sim	the PC simulator binary, from its own folder	the simulator was built
crosspad-pc	the crosspad-pc app manager (scripts/app_manager.py)	crosspad-pc is checked out

With the Arduino option the installer also adds crosspad-arduino and pio.

Firmware helper scripts

Run from the platform-idf root as python3 tools/<script>. The ESP scripts pick the build of the connected (or remembered) board revision by default.

Tools used only by the release pipeline are not listed here.

ota_flash.py

Flash firmware over USB CDC while the board runs. See Update firmware over USB.

option	what it does
firmware	Image to send (default: build_<rev>/CrossPad.bin of the board being flashed)
-p, --port	Serial port (auto-detected if omitted)
--board	Revision of the image to take; needed when the board’s own revision is unknown
--device	crosspad-hil device id, when several boards are connected
--delta	Send a delta patch instead of the full image (needs --base-fw)
--base-fw	The image currently on the device
--patch	A pre-generated delta patch (skips patch generation)
--force	Flash an image built for another revision, or a board of unknown revision

fs_transfer.py

Assets partition and file transfer over USB CDC. -p / --port (serial port, auto-detected if omitted) goes before the subcommand, for example python3 tools/fs_transfer.py -p <port> ls /sdcard.

subcommand	what it does
assets [image]	Flash a whole LittleFS assets image (default: the board’s build); --force skips the superblock check
push LOCAL REMOTE	Copy a file to the device
pull REMOTE [LOCAL]	Copy a file from the device
dump LOCAL	Read the assets partition back as an image
ls REMOTE	List a directory under /assets, /spiflash or /sdcard
roots	Show the mounts and their usage
stat REMOTE	Size and type of one path
rm REMOTE	Delete a file or an empty directory
mkdir REMOTE	Create a directory

crosspad_board.py

Which board revision to build and flash for: --board, then the connected board, then the last choice in crosspad.local.json. Exit 2 when nothing is known.

option	what it does
none	Print the decision and where it came from
--board	Use this revision (v1 or v2)
--device	crosspad-hil device id, when several boards are connected
--set	Remember this revision and stop
--idf-args	Print the idf.py -B / -DSDKCONFIG arguments for the revision
--json	Machine-readable output

bench.py

One entry point for a test board; it finds the crosspad-hil venv itself. Exit codes follow crosspad-hil.

subcommand	what it does
check	Check the connected test setup and print a fix for each problem
ready	Put the test board in a known state: CDC profile, mic route, a kit loaded
flash [--assets]	Flash the build for the connected board and prove it landed; --assets also reflashes the assets partition
test SCENARIO...	Run HIL scenarios with this bench’s flags
recover	Reflash over UART through the STM bridge port, for a board that does not answer over USB CDC; --port, --build, --sdkconfig
hil ARGS...	Raw crosspad-hil, venv resolved

requestBootloader.py

Ask the ESP32-S3 to enter its ROM bootloader over MIDI SysEx or USB CDC.

option	what it does
--method	Transport order, comma-separated (default midi,cdc)
--device	Part of the device name to search for (default Crosspad)
--vid	USB vendor ID in hex, for CDC
--pid	USB product ID in hex, for CDC
--skip-bootloader-check	Do not check whether the device is already in bootloader mode

crosspad-hil

crosspad-hil 1.6.0, installed with pip install "crosspad-hil[all] @ git+https://github.com/CrossPad/crosspad-hil". Options every command takes: -d / --device (device id or port; implicit with one board), --json, --holder (the name you reserved a shared board with), --bench-force. Exit codes: 0 pass, 1 test failed on the device, 2 setup problem. See Test on hardware (HIL).

command	what it does
devices	List attached CrossPads and their ports; --watch re-lists every second
doctor	Check dependencies, permissions, port locks and devices
console	STM bridge console: tail it, or wait for --expect patterns
cdc	Send a raw CDC verb and print the reply
app	list, start NAME, stop, versions
kit	list, load ID, status, push DIR, from-fpc, to-fpc
pad	press, release, pressure, stats, notes
ui	snapshot, focus REF, press, rotate N
led	state: the LED controller’s model as a 4x4 grid
mem	Free, largest and minimum internal and PSRAM memory; --blocks for the histogram
ble	Board BLE: status, start, stop, scan, devices, enable, connect, disconnect, send
ble host-*	This computer’s radio: host-scan, host-listen, host-send, host-latency
midi	sysex HEX, note on|off N, echo; hub (host only) keeps fixed ALSA MIDI ports open for a DAW
companion	Send one companion verb over SysEx (works in the audio profile)
usb-mode	get, or set default|audio
audio	route, level, gain, tasks on|off; nodes (host only) exposes the board as PipeWire nodes
fl	Host only: FL Studio project template install / status
reaper	Host only: REAPER control script install / status
snapshot	One-call device state: apps, UI, kit, LEDs, pads, memory, BLE
stim	Play the pads on a schedule; reports the PAD_STATS delta and drops
diagnose	Diagnostic bundle: reset reason, decoded backtrace, heap, console context
capture	Record the UAC2 capture endpoint to a WAV (switches profile and back)
analyze	Offline verdict on a WAV (onset, click, silence, multitone, velocity, psd…)
jam	Script and analyse a live set offline: script, analyze, kits, synth
flash	OTA-flash firmware over CDC (leaves the audio profile if needed); --delta, --base-fw
bootloader	Request the ESP ROM bootloader (--esp, default) or STM DFU (--stm)
run	Run a HIL scenario, e.g. crosspad-hil run smoke
bench	Reserve a shared test board: claim, renew, release, status, md
record	Record a CDC transcript (commands from stdin) for replay tests
serve	NDJSON daemon on stdio (used by crosspad-mcp)