CLI reference

Install

brew trust embeddedci-com/tap
brew install --cask embeddedci-com/tap/benchpod
benchpod --version

# or the plain binary (the releases/latest/download URL is always the newest release)
curl -fsSL -o benchpod.tar.gz \
  https://github.com/embeddedci-com/benchpod-cli/releases/latest/download/benchpod_Darwin_arm64.tar.gz
tar -xzf benchpod.tar.gz benchpod
sudo mv benchpod /usr/local/bin/

brew trust embeddedci-com/tap
brew install --cask embeddedci-com/tap/benchpod
benchpod --version

# or the plain binary (the releases/latest/download URL is always the newest release)
curl -fsSL -o benchpod.tar.gz \
  https://github.com/embeddedci-com/benchpod-cli/releases/latest/download/benchpod_Linux_x86_64.tar.gz
tar -xzf benchpod.tar.gz benchpod
sudo mv benchpod /usr/local/bin/

# PowerShell (use benchpod_Windows_arm64.zip on an ARM machine)
Invoke-WebRequest https://github.com/embeddedci-com/benchpod-cli/releases/latest/download/benchpod_Windows_x86_64.zip -OutFile benchpod.zip
Expand-Archive benchpod.zip -DestinationPath "$env:LOCALAPPDATA\benchpod"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\benchpod", "User")
# open a new terminal, then:
benchpod --version

With Homebrew, brew upgrade --cask benchpod picks up later releases. Pre-built binaries for macOS, Linux and Windows (amd64 + arm64) are attached to every GitHub release. flash-self needs dfu-util:

Flashing a target also needs OpenOCD (see Flashing below).

Setting up a new pod

benchpod setup is the one command for a new pod. It runs five steps and says what it did in each: 1/5 Find the pod (USB and the LAN, as discover does; the global --connection picks one instead), 2/5 Network (waits for an Ethernet lease, or joins Wi-Fi with --ssid), 3/5 Board I/O voltage, 4/5 embeddedci.com (signs in with login and registers the pod) and 5/5 Save the connection. It ends with the next steps: wiring, a first flash, a first test. A step that is already done is skipped, so running it again is safe, and a pod registered to another account is left alone.

# Interactive: asks what it needs (Wi-Fi or Ethernet, the I/O voltage, whether to register)
benchpod setup

# A pod you already know the address of, Wi-Fi from a secret, a 1.8 V board, no prompts
benchpod --connection /dev/cu.usbmodem1103 setup \
  --ssid my-bench-wifi --password-stdin --la-voltage 1.8V --yes < wifi-password.txt

With --yes it never prompts: it registers without asking, and stops naming the flag to pass when it needs an answer (for example --la-voltage). --no-register skips embeddedci.com for a pod you only use over the LAN. The flags are in the reference.

benchpod status then shows the pod at a glance, including whether a newer firmware is out and whether the pod is on your account; --json prints the raw status instead. Over USB it prints the console's own status text.

$ benchpod status
BenchPod at 192.168.1.221:8080
  Firmware      3.8.0 (latest)
  Gateware      48
  Board         stm32h563 v3
  I/O voltage   3.3 V
  Target power  off
  Network       192.168.1.220 (ready), Wi-Fi connected
  Cloud         registered, connected, on your account as benchpod-baea06

Finding a pod

benchpod discover answers two questions at once: can a pod be found, and does it work? It probes every USB port for a bench-pod console and browses the LAN over mDNS, then calls the API of each pod it found on the network, so the report says whether the pod actually answers commands and whether it is registered with the cloud, rather than only that something replied to a broadcast. A pod reachable both ways is reported once, with the two entries matched up.

It also reports whether each pod is already registered to an account, on both transports: the USB half reads it off the pod's own console, so the answer comes even from a pod with no network yet. That is what tells you whether a pod you were handed still needs benchpod login and benchpod register, or arrived already claimed and needs nothing. Firmware too old to report it says nothing rather than guessing.

When this computer is signed in (benchpod login), a registered pod is also checked against that account: discover prints its name when it is yours, and says registered to a different embeddedci.com account when it is not. That is usually a second account. A pod set up for you is on the account your activation email was sent to; sign in with that address (benchpod login --force).

Because it probes USB, it finds a pod that has no network at all, which is the state a pod ships in. When nothing is found, the output lists the ports it probed and the likely causes (charge-only cable, no firmware, mDNS blocked). --save stores the address as the default connection when exactly one pod is found, preferring the network address; --no-usb / --no-network restrict the search, and --wait / --probe-timeout tune how long each half gets.

Connection

The global --connection flag is the single place that says where and how to reach the pod; the transport is inferred from its value.

The global flags are also settable via a BENCHPOD_* environment variable (e.g. BENCHPOD_CONNECTION=usb, BENCHPOD_TIMEOUT=2m), with precedence flag > env > saved default. Command flags are flags only.

With --connection usb and firmware 3.9.0 or later, every command works over the pod's USB network adapter, including install-blobs, cloud ca and cloud proxy (the USB link may change the company CA and the proxy; the pod's Ethernet and Wi-Fi may not). Firmware 3.9.0 has no uploads on its USB console, so it needs benchpod 0.6.0 or later. On older firmware the USB console runs status, la voltage, install-blobs and the cloud settings, as before. set-wifi, show-network, clear-wifi, dfu, identity, lan-policy, sig-policy and bootsel use the USB console (physical presence). cloud ca and cloud proxy also work over embeddedci.com (except cloud ca set).

Over embeddedci.com

embeddedci:<name> reaches a registered pod through embeddedci.com from any network, whether it comes from --connection, BENCHPOD_CONNECTION or the saved default. These commands work that way: status (including --json), ping, la voltage, la pullup, la status, la step, generate, cloud ca show / clear, cloud proxy show / set / clear, lan-policy, sig-policy and deregister. It authenticates with BENCHPOD_API_KEY (sent as Authorization: ApiKey), else the benchpod login session; BENCHPOD_API_BASE picks the server.

These refuse over the cloud and name the alternative, so run them on the LAN or over USB: capture, stream, measure, test, flash, spi-flash, register, cloud ca set, discover, set-wifi, show-network, clear-wifi, install-blobs, bootsel, dfu and flash-self. A saved embeddedci: default does not get in the way of the USB-only commands: they find the pod on USB by themselves. A pod that is busy (another holder has its lease) exits with code 4, a pod that is offline on embeddedci.com with 5, and a command that needs an owner or admin role you lack with 3.

The saved connection

benchpod discover --save and benchpod set-connection (which also accepts embeddedci:<name>) store the default connection in ~/.config/benchpod-cli/config.json, a file with "version": 1. It is shared: the Python SDK (BenchPod() with no connection) and the MCP server (connect with no argument) read the same default, after an explicit connection and BENCHPOD_CONNECTION. The pytest plugin uses it only when you pass --benchpod-connection=saved.

benchpod setup and discover --save save the pod's Ethernet or Wi-Fi address when it has one, so the default keeps working from other machines and after the pod moves. A pod that only has its USB network link (firmware 3.9.0 and later) is saved as usb, never as its 10.237.x.y address, which only works while the pod is plugged into this computer.

The wiring profile

Over a network connection, when you are signed in and the pod is on your account, flash and spi-flash take their pins from the wiring profile stored on embeddedci.com (the Wiring tab of the pod's workspace): --swclk, --swdio, --nreset and --target default to swd_swclk, swd_swdio, swd_nreset and swd_target; --sck, --mosi, --miso and --cs default to spi_sclk, spi_mosi, spi_miso and spi_cs. Flags you pass win (--nreset=false overrides a profile that says true). Target power never comes from the profile. If the lookup fails (it gives up after 6 seconds), the CLI prints one warning and uses the defaults.

Commands

# A new pod: the guided setup (find it, network, I/O voltage, register, save the connection)
benchpod setup

# Find every pod on this machine and this LAN, and check each one works:
benchpod discover
benchpod discover --save     # save it as the default when exactly one is found

# Save a default connection so later commands can omit --connection:
benchpod set-connection 192.168.1.5
benchpod set-connection usb

# Reachability / state:
benchpod ping
benchpod status           # readable summary; --json for the raw status

# Instruments (network):
benchpod la voltage 3.3V                          # the DUT's I/O voltage; LA operations need it (network or USB)
benchpod generate --waveform sine --freq 1kHz --duration 2s   # DAC waveform
benchpod measure --waveform sine --samples 1024   # DAC + ADC loopback
benchpod capture --samples 1024 --output csv      # ADC snapshot
benchpod stream ...                               # asynchronous ADC capture
benchpod test ...                                 # diagnostic pattern, no FPGA
benchpod la pullup 3 on                           # pull-up on LA3
benchpod la status
benchpod la step --la 6 --steps 200 --delay 500us --dir-la 7 --direction 1

# A pod on this computer's USB-C cable only: keep it online on embeddedci.com
benchpod usb-bridge install

# Wi-Fi (always over the pod's USB console; turns the pod's USB network off):
benchpod set-wifi --ssid my-bench-wifi
benchpod show-network     # the pod's IP (wired lease included), SSID, state, RSSI
benchpod clear-wifi

# Firmware:
benchpod flash ...        # the target's firmware, SWD via OpenOCD's CMSIS-DAP backend
benchpod spi-flash ...    # read/erase/program an SPI NOR flash on four LA pins
benchpod flash-self       # the pod's own firmware over USB DFU (latest release); a blank pod needs BOOT0 + RESET first
benchpod flash-self --enter-dfu   # same, restarting a pod that already runs firmware into DFU for you
benchpod install-blobs    # the gateware and ESP32-C3 images the pod's firmware goes with (USB)
benchpod dfu              # reboot the pod into its DFU bootloader (USB console only)

# Cloud account (optional):
benchpod login [--server-url https://www.embeddedci.com]
benchpod register --connection 192.168.1.5      # or --connection usb for a pod on USB-C
benchpod deregister ...
benchpod logout

# Pod settings (cloud with --device-name, or USB):
benchpod lan-policy --device-name benchpod-baea06          # show
benchpod lan-policy set locked --device-name benchpod-baea06
benchpod sig-policy set permissive --connection usb
benchpod identity --connection usb                         # show the device identity
benchpod cloud ca set acme-root.pem --connection usb       # company CA for a TLS-inspecting proxy
benchpod cloud proxy set proxy.corp:3128 --user alice --connection usb

Run benchpod <command> -h for the flags of any subcommand, or see the command reference. benchpod completion bash|zsh|fish|powershell prints a shell completion script.

Flags that take a physical quantity accept it with its unit: --freq 2kHz, --sample-rate 10MHz, --duration 2s, --delay 50us, and benchpod la voltage 3.3V. The older flags with the unit in their name (--sample-rate-mhz, --duration-ms, --delay-us) keep working; pass one or the other, not both.

Exit codes

Scripts can tell why a command failed from its exit code. The error goes to stderr with a [benchpod] prefix.

A refusal is printed word for word as the pod sent it. For a locked: (LAN policy), busy: (cloud lease) or forbidden: (missing role) refusal the CLI adds what to do next.

Flashing (CMSIS-DAP)

flash always drives host-side OpenOCD. The pod holds no flash intelligence and OpenOCD's exit code is the verdict. The pod runs a CMSIS-DAP processor locally and OpenOCD's cmsis-dap TCP backend ships whole DAP transfers, so a flash is one round-trip per DAP command instead of thousands of per-bit round-trips, so it is fast even over the network. It works over the network and over USB, and needs a recent OpenOCD with the cmsis_dap_tcp backend (post-0.12.0, below). The CLI checks for the backend up front and fails with clear advice if it's missing.

# Homebrew's stable open-ocd is 0.12.0, so build it from HEAD
brew install --HEAD open-ocd

# the xPack OpenOCD 0.12.0-7 snapshot carries the TCP backend
V=0.12.0-7
curl -fsSL "https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v$V/xpack-openocd-$V-linux-x64.tar.gz" \
  | sudo tar xz -C /opt
export PATH="/opt/xpack-openocd-$V/bin:$PATH"

# PowerShell: the xPack OpenOCD 0.12.0-7 snapshot carries the TCP backend
$V = "0.12.0-7"
Invoke-WebRequest "https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v$V/xpack-openocd-$V-win32-x64.zip" -OutFile openocd.zip
Expand-Archive openocd.zip -DestinationPath "$env:LOCALAPPDATA\xpack"
$bin = "$env:LOCALAPPDATA\xpack\xpack-openocd-$V\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$bin", "User")
# open a new terminal so it picks up the PATH

Name the SWD pins with --swclk and --swdio, then pass --target with --file (or your own -c commands). With the target's NRST wired to the pod's reset pin, add --nreset: the target is held in reset while OpenOCD connects, so running firmware cannot turn SWD off first. --target-power 1 powers the target first.

SPI flash

spi-flash reads, erases and programs a 25-series SPI NOR flash (W25Q, MX25, GD25, IS25, ...) wired to four LA pins, through the pod's SPI master. It needs gateware v45 or newer (the spi_master capability), the LA voltage set, and a network connection.

PINS="--sck 3 --mosi 4 --miso 5 --cs 6"
benchpod spi-flash id $PINS                          # JEDEC ID, size, status register
benchpod spi-flash write fw.bin $PINS --nreset       # erase, program, verify
benchpod spi-flash write app.bin $PINS --addr 0x100000 --hz 4000000
benchpod spi-flash read dump.bin $PINS               # whole part (or --addr/--len, e.g. --len 1M)
benchpod spi-flash erase $PINS --addr 0 --len 64K    # or --chip

write erases the range the file covers, programs it and has the pod read every chunk back. --hz picks the SCK rate (rounded down, 190 kHz to 6 MHz) and --mode is 0 or 3; 3-byte addresses reach the first 16 MB. With --nreset the DUT is held in reset for the whole run, so its own controller stays off the bus. The pins and the reset are always released at the end, also after an error or Ctrl-C. The pod does not clear block-protect bits.

Updating the pod itself

flash-self writes the pod's own firmware over USB DFU with dfu-util. With no argument it fetches the latest release; the pod must be in its DFU bootloader (BOOT0 high at reset for a blank pod, or --enter-dfu for a running one), and it waits up to --wait for it. It refuses an image that does not fit the pod's flash.

Over the network. --network sends the image over the pod's own API instead: its USB network adapter (firmware 3.9.0 or later, no Wi-Fi set up) or the --connection address over Ethernet or Wi-Fi. The pod stages it in PSRAM, checks its SHA-256 and signature, writes its flash and restarts, and the CLI then installs its blobs the same way. No dfu-util, but the pod must be running firmware, and a network access setting of Instruments only or None refuses it over Ethernet and Wi-Fi. DFU stays the default because it also recovers a pod whose firmware does not start. A pod on embeddedci.com is updated from the web app.

Firmware 3.9.0 and later: update the CLI (brew upgrade --cask benchpod) and the Python packages (pip install --upgrade embeddedci embeddedci-mcp) before you update the pod. 3.9.0 changes how the pod connects over USB, and older tools may not reach it afterward. The update notice on the BenchPod page and the Update firmware window say so too.

benchpod flash-self                         # latest release
benchpod flash-self --enter-dfu             # reboot a running pod into DFU first
benchpod flash-self ./bench_pod_stm32.bin   # a local build
benchpod flash-self --firmware-version v3.5.1
benchpod flash-self --network               # over the USB network adapter (firmware 3.9.0+), no dfu-util
benchpod flash-self --network --connection 192.168.1.42   # over Ethernet or Wi-Fi
benchpod install-blobs --dir stm32h563/build/blobs   # blobs from a local build

Firmware from 3.5.0 on keeps the iCE40 gateware and the ESP32-C3 Wi-Fi image in the pod's W25Q flash. After writing the firmware, flash-self installs the ones the pod lacks from the same release; install-blobs does that step on its own (--release, --dir, --only gw0,gw1,esp,bridge, --force), and set-wifi runs it first when the ESP32-C3 image is missing.

Signatures. Releases can publish a signed manifest, <asset>.sig, next to the firmware and each blob. flash-self and the blob install check it and print one line, such as signature: ok (release-1 key 9b5cc58445e62d88, release 3.6.0) or signature: none (this release is not signed). Firmware that checks signatures itself also gets the manifest and its verdict is printed as pod signature check: .... For now the CLI only reports: a missing or failing signature never stops a flash or an install, and the exit status does not depend on it. What the pod itself accepts is its sig-policy.

Update reports. When you are signed in (benchpod login or BENCHPOD_API_KEY), the CLI tells embeddedci.com about each firmware change it makes: flash-self, an update over the USB network or the LAN, and install-blobs. The report carries the pod's identity key and name, the old and new firmware and gateware versions, how it was installed and the CLI version, so the pod's history on embeddedci.com includes updates that did not go through the web app. It is best effort: a failed report never fails the update. Turn it off with BENCHPOD_NO_FIRMWARE_REPORT=1 or --no-firmware-report. Signed out, nothing is sent.

USB-C, Ethernet and Wi-Fi

A pod connects in one of three ways. At a desk, one USB-C cable to your computer carries power and the full API: from firmware 3.9.0 the pod is a USB network adapter as well as a console, on macOS, Linux and Windows 11 with no driver (Windows 10 is supported but not tested), and two pods on one computer each get their own address (not yet tested with two physical pods). In a lab or rack it sits on Ethernet, powered from USB-C. On v3 pods Wi-Fi is an option, set once with set-wifi; while Wi-Fi is set up the USB network is off.

Over Ethernet or Wi-Fi the pod reaches embeddedci.com on its own. On USB-C alone it has no internet of its own, so the usb-bridge on the computer carries its cloud link. Install it once as a background service and the pod stays online in the web app after the computer or the pod reboots:

# Once per computer: run the bridge as a background service (starts at login)
$ benchpod usb-bridge install

# Is it installed and running, and which pod does it carry?
$ benchpod usb-bridge status

# Remove the service (also clears the pod's cloud proxy)
$ benchpod usb-bridge uninstall

# Or run it in the foreground for this session only (Ctrl-C stops it)
$ benchpod usb-bridge

sudo tee /etc/udev/rules.d/70-benchpod.rules <<'EOF'
# BenchPod: keep ModemManager off the pod's USB console; let the desktop user open it
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", ENV{ID_MM_DEVICE_IGNORE}="1", TAG+="uaccess"
ATTRS{idVendor}=="1209", ATTRS{idProduct}=="0001", ENV{ID_MM_DEVICE_IGNORE}="1", TAG+="uaccess"
EOF
sudo udevadm control --reload-rules && sudo udevadm trigger

# Show the setting and whether the USB network is on now
$ benchpod usb-network --connection usb

# Turn it off: the pod restarts its USB as a console only, and the computer sees no network adapter
$ benchpod usb-network off --connection usb

# Turn it back on, over the console
$ benchpod usb-network on --connection usb

Pod policies: LAN and signatures

Two settings the pod keeps in its config flash. benchpod lan-policy and benchpod sig-policy show them; ... set <value> changes them. Pick the pod with --device-name / --device-id (through embeddedci.com) or with --connection usb. Over the LAN they can only be shown.

The web app calls lan-policy Network access without sign-in (the pod's Settings tab): open is Full, locked Instruments only and off None. It covers the API on Ethernet and Wi-Fi, which has no login. The USB connection stays on under every value, because using it needs physical access to the pod.

$ benchpod lan-policy --device-name benchpod-baea06
LAN policy of benchpod-baea06: locked (read and instrument control only on the LAN)
$ benchpod sig-policy set required --device-name benchpod-baea06

• Over the cloud a change needs an organization owner or admin (an API key needs the benchpod:admin scope).
• The cloud can only make sig-policy stricter; loosening it needs the USB console.
• With lan-policy off, LAN tools (SCPI/VISA, LAN discover) stop working until it is set back over the cloud or USB.

LAN TLS

Pods with firmware 3.9.3 or later serve the same API on port 8443 with TLS. For an address on the default port, benchpod uses 8443 when the pod has it and pins the pod's certificate the first time (in known_pods.json next to the config, shared with the SDK); older pods stay on plaintext 8080. A different certificate later stops the command with both fingerprints. --tls on|off overrides, --tls-ca verifies a certificate signed by your own CA instead of pinning.

$ benchpod lan-tls --connection 192.168.1.220
LAN TLS of 192.168.1.220:8080 (connected over TLS)
  port        8443
  https-only  off
  certificate CN=benchpod-baea06 (generated, EC P-256), valid to 9999-12-31
  sha256      3f1c...
  pinned      yes, for 192.168.1.220:8443
$ benchpod lan-tls https-only on
$ benchpod lan-tls set-cert --cert pod.pem --key pod.key
$ benchpod lan-tls trust        # after a change made elsewhere

• https-only on turns plaintext 8080 off on Ethernet and Wi-Fi (the USB cable keeps it). The web app's pod Settings has the same switch, HTTPS-only API.
• The pod refuses https-only off, regenerate and set-cert over plaintext Ethernet or Wi-Fi: use TLS (the default), --connection usb or --connection embeddedci:<name>.
• VISA raw sockets have no TLS: with HTTPS-only on, run a local wrapper such as socat with the certificate from benchpod lan-tls show --pem.

Device identity

The pod's identity is an Ed25519 key in its own flash; its name (benchpod-a1b2c3) comes from the public key, and embeddedci.com knows the pod by it. benchpod identity shows it, and says why when the pod has none. benchpod identity wipe erases the key and makes a new one; it works only over the USB console, so it needs someone at the pod.

$ benchpod identity --connection usb
$ benchpod identity wipe --connection usb     # asks first; --yes skips the question

After a wipe the pod is a new pod to embeddedci.com: deregister the old record with benchpod deregister --device-name <old name> (its data is kept and the name is freed), power-cycle the pod, register it again with the old name, and set its wiring profile again.

Cloud link behind a company network

On a network whose proxy inspects TLS, the pod's cloud link fails because the proxy re-signs embeddedci.com with a company root the pod does not trust. Some networks also only reach the internet through an HTTP proxy. benchpod cloud ca and benchpod cloud proxy set both over the USB console; the LAN can show them but not change them.

$ benchpod cloud ca set acme-root.pem --connection usb
acme-root.pem: 1 certificate
  CN=Acme Root CA,O=Acme Corp
    SHA-256 3b1f...c2d9
Uploading 652 bytes to the pod on /dev/cu.usbmodem1101 ...
The pod reconnects to the cloud, trusting this CA in addition to its built-in roots.

$ benchpod cloud proxy set proxy.corp:3128 --user alice --connection usb
Proxy password:
The pod reconnects to the cloud through proxy.corp:3128.

• cloud ca set takes a PEM file (at most 16 KB), prints each certificate's subject and SHA-256, refuses anything that is not a certificate, and uploads only the certificates. They are trusted in addition to the built-in roots. cloud ca clear removes them.
• cloud proxy set <host:port> with --user takes the password from a prompt, --password-stdin or --password. The pod never reports it back. With a LAN address as the target, the CLI first warns that the LAN API is plain TCP and the password would cross the network unencrypted. cloud proxy clear removes the proxy.
• The pod reconnects to the cloud after every change.

Cloud auth

Direct firmware commands are unauthenticated and send no tokens; they assume a trusted local network.benchpod login (device-login flow) and benchpod register authenticate with embeddedci-server for cloud features such as driving a pod by name or registering a new pod. See Security & trusted repos for the model.

• benchpod register --connection <pod-ip>: claim a pod into your org and wait until it is connected. It is named after the pod (benchpod-a1b2c3); names are unique within an org, so pick another with --device-name if one is taken. The pod is provisioned to connect to api.embeddedci.com. Running it again on the same pod is always safe: it keeps the pod's record, name and history.
• benchpod login: authenticate the CLI for cloud operations. It prints the account it signed in to (Logged in as you@example.com), so a pod set up for you can be checked against the address your activation email was sent to. benchpod logout deletes the cached tokens; it does not deregister anything.
• benchpod deregister --connection <pod-ip>: detach a pod from your org. Its record is disabled, not deleted: its captures, waveforms and wiring are kept, and registering the same pod again restores them. Registering it for another account starts that account with a fresh record. A pod you cannot reach can be deregistered with --device-name or from the BenchPod page. Deleting or disabling an account deregisters its pods automatically; pods in a shared org pass to another member.