Docs / Command line

Run your board from the terminal

The hardlabs command line starts a simulation of your board, runs your firmware on it and opens a shell. In that shell you see the firmware's console, read the board's state, and plug in power, move a sensor or flip a line while the firmware runs.

The simulation runs on HardLabs' servers. Your source code stays on your machine: the only thing uploaded is the firmware image you pass, and it is used for your session alone.

Before you start

  • Node.js 18.17 or later (node --version).
  • A HardLabs account. Sign up with the e-mail address your board was shared with. No board with us yet? Request a pilot.
  • A simulation to run. Every account can run hardlabs/demo-board, a board we built, to try things out. We share your board's simulation with your e-mail address when it is ready. You can also build one yourself from your design files with hardlabs create.
  • Optional: your own firmware build, as an ELF file (for example build/zephyr/zephyr.elf). Without one, the simulation runs the firmware it was built with.

1. Install

npm install -g hardlabs

Check it with hardlabs --version. To update later, run npm install -g hardlabs@latest. If you would rather not install anything globally, put npx hardlabs in front of each command instead.

It runs on macOS, Linux and Windows: the simulation runs on our servers, so the CLI needs only Node.js.

  • macOS: brew install node.
  • Linux: your distribution's nodejs package if it is 18.17 or later, or nvm.
  • Windows: winget install OpenJS.NodeJS.LTS, then open a new PowerShell, cmd or Windows Terminal window.
  • WSL: install Node.js and the CLI inside WSL, as on Linux. hardlabs login opens your Windows browser.

2. Sign in

hardlabs login

This opens hardlabs.io in your browser with a short code. Sign in if you need to, check that the code matches the one in your terminal, and approve. The terminal finishes by itself and tells you how many simulations you can open.

hardlabs whoami

This shows which account this computer is signed in as. It should be the e-mail address your board was shared with.

The sign-in is saved on this computer, readable only by you. It appears as "CLI on <computer>" under Settings → CLI access, where you can revoke it. It can list and run the simulations you have access to, and nothing else.

No browser on that machine (over SSH, a Linux server with no display, or in CI): run hardlabs login --no-browser and open the printed link on any device. Or create a token under Settings → CLI access and pass it with hardlabs login --token <token>, or set it as HARDLABS_TOKEN.

3. Find your simulation

$ hardlabs sims
  acme/sensor-board@v1.2.0  latest  Sensor board rev B

Demo — a board we built, for trying things out
  hardlabs/demo-board@rev-a  demo latest  HardLabs demo board rev A

Simulations are named owner/project@version. You can type less than the full name:

You typeYou get
acme/sensor-board@v1.2.0exactly that version
acme/sensor-boardits latest published version
sensor-boardthe one project with that name, latest version

If a name matches projects from two owners, the CLI lists both and asks for the full name. It never guesses. Boards you started on the website are listed with hardlabs sims --all.

4. Run your firmware

Try it now, on the demo board
hardlabs -s hardlabs/demo-board
With the firmware the simulation was built with
hardlabs -s acme/sensor-board
With your own build
hardlabs -s acme/sensor-board -f build/zephyr/zephyr.elf
A bootloader and an app, as raw images at their flash addresses
hardlabs -s acme/sensor-board \
  -f build/bootloader.bin@0x08000000 -f build/app.bin@0x08010000

The board starts, your firmware boots and you are in the board's shell. The firmware's console output scrolls in above the prompt without disturbing what you are typing. An ELF or Intel HEX file carries its own addresses; a raw .bin needs the address it is flashed at, as J-Link's loadbin takes it. Images can be up to 64 MB each.

To stop the simulation, type quit, press Ctrl-D, or press Ctrl-C twice. Leaving the shell always stops the simulation.

5. Drive the board

Type help in the shell for the full list. These are the commands to start with:

Command
help [part]every command; help J2 (or J2 help) for everything one part takes and shows, with the names to call it by
status [panel]the board's panels and their values, as the website shows them
watch [seconds]redraw them every few seconds until Ctrl-C
controls [panel|part]what you can change on the board, and how; controls U4 for one part
do <control> [values]change it, e.g. do input-source.bench-supply volts=5.08 or do U4.enable on
parts [filter=value]every part on the board, or the ones on a bus, at an address, or wired to a part
fw <text>type into your firmware's own shell (Tab completes)
shortcutsfirmware commands this board suggests
console [n]the last n lines of the firmware's console
follow on|offstream console lines as they arrive, or stop
follow serial <port>stream what the board sends on a serial port (see below)
serial read <port>what went over a serial port, both ways, since the last read
serial open <port> [path]a serial port for your own tools (see below)
memorythe board's memory chips: EEPROM, F-RAM, SPI NOR (see below)
restartpower-cycle the board; memory chips keep what they hold
wait <time>let simulated time pass: wait 2s
expect "<text>" [within <time>]wait for text on the console, in order, each on a later line
unit-tests [within <time>]a test binary's Unity or GoogleTest results, as the SDK reads them
scope [panel]what each part's model covers, what it assumes, and what it leaves out
gdb [port|off]let a debugger connect (see below)
quitstop the simulation
A first session
hardlabs> status              # what the board looks like now
hardlabs> help                # the commands, then every part you can ask about
hardlabs> help J2             # what one part takes and shows
hardlabs> controls            # what you can change, on every part
hardlabs> do input-source.bench-supply volts=5.08
hardlabs> console 20          # what the firmware said about it
hardlabs> scope               # how far each part's model goes

Each part also answers to its reference designator from your schematic, which tells identical parts apart: do U4.extra-load-current 0.5, status U6, parts bus=i2c0. See your board's parts.

Every value in the shell comes from a model of the part. Before you blame your firmware for a surprising reading, check scope: it says what the model covers and what it does not.

Several simulations at once

One account has one session per board: the website, the CLI, your scripts and your agent all join it, and starting it again restarts it for all of them. To run the same board more than once, name each run with --instance (or HARDLABS_INSTANCE). Each name is a simulation of its own, beside the others.

hardlabs -s company_name/board_name -f build/app.elf --instance bench-2
hardlabs run tests/boot.yaml --instance ci-41

Your account runs a set number of simulations at once. A start past that number waits in line and says its place; it starts by itself when one of yours stops, and Ctrl-C leaves the line. hardlabs status lists what is running and what is waiting (--json for a script).

$ hardlabs status
20 running, 30 waiting in line · this account runs up to 20 at once
  running  company_name/board_name@v1.2.0  ci-1   for 4 min
  ...
  waiting  company_name/board_name@v1.2.0  ci-50  number 30 in line, for 40 s

Pin a board revision for your team

Put a hardlabs.json at the root of your firmware repository:

hardlabs.json
{ "simulation": "acme/sensor-board@v1.2.0" }

Then everyone on the team, and CI, gets the same board with hardlabs -f build/zephyr/zephyr.elf. When a newer version is published, the CLI tells you.

The same file can hold the rest of a start, so the team doesn't retype it. Its keys are the flags' (simulation, firmware, load_memory, memory, save_memory, held, serial, and startup for shell lines run once it boots), and its paths are relative to it. --config picks another file, in YAML or JSON:

test/first-boot.yaml
simulation: acme/sensor-board@v1.2.0
firmware:   [../build/zephyr/zephyr.elf]
memory:     [U7=erased, U9=erased]
serial:     {rs485: /tmp/ttyUSB0}
startup:    [follow serial rs485]
hardlabs --config test/first-boot.yaml --mem U7:0x40=0x0002

A flag replaces its key, and -f the whole firmware list; --mem and --serialadd to the file's. The CLI says which keys it used when it starts. Scenario files take firmware, load_memory and memory too, the MCP server reads the file the same way, and the Python SDK takes it with --hardlabs-config.

Fill memory chips, keep snapshots

External EEPROM, F-RAM and SPI NOR flash start blank, as on a board fresh off the line. If your firmware expects something in them (settings, calibration, a bootloader's image header, a second firmware slot), fill them before it boots:

hardlabs -s acme/sensor-board -f build/zephyr/zephyr.elf \
  --mem U7=settings.bin --mem U7:0x100=calibration.bin --mem U9=erased
You writeWhat goes in
U7=settings.binthe file, from the chip's first byte
U7:0x100=calibration.binthe file, from offset 0x100
U7:0x40=0x00010203these bytes
U9=erased0xFF from the offset to the end, as erased flash
U7:0x0=fill:0x00:6464 bytes of 0x00
  • Name a chip by its reference designator from the schematic (U7, any case). memory in the shell lists them.
  • Entries apply in the order you give them, so a later one overwrites what an earlier one wrote. --set is another name for --mem. The chips hold these bytes before the CPU runs its first instruction.
  • To use a file called erased, or one whose name starts with 0x, write ./erased.

A chip's contents last as long as the session. Save them all when you quit, and start the next run from them:

hardlabs -s acme/sensor-board -f build/app.elf --save-memory nvm/
hardlabs -s acme/sensor-board -f build/app.elf --load-memory nvm/ --mem U9=erased
hardlabs memory inspect nvm/          # the board, the firmware and the chips it holds

nvm/ holds one .bin per chip and a memory.json. The Python SDK reads and writes the same folders, so a snapshot saved in pytest loads here and the other way round. When a snapshot was saved with other firmware, the CLI says so as it starts. That's expected when you test an upgrade on old data. It matters when something in the chips describes the firmware, such as a bootloader's image checksum: make a new snapshot with the new build.

If your bootloader expects an image header or a second copy in external flash, let it write them once through your own update procedure and save the result. Every later run starts from there, without the update. To change a chip by hand before boot, start with --held, use memory write U7 0x40 0002, then run.

In the shell
memorythe board's memory chips, with their sizes
memory read <chip> <offset> [length]bytes as hex: memory read U7 0x40 16
memory write <chip> <offset> <hex>write bytes now, as if another device did
memory save <dir>every chip, as a snapshot
memory save <chip> <file>one chip into one file; it loads back with --mem U7=file
memory inspect <dir>what a snapshot holds
restartpower-cycle the board; the chips keep what they hold

Serial ports for your own tools

If you talk to your board over a serial line (RS-485, a debug UART, a binary protocol), see what it sends, or point your own program at it:

hardlabs> follow serial rs485
hardlabs> serial rs485 01 03 00 00 00 02 C4 0B after 1ms
[12.0040 s] rs485 → 01 03 00 00 00 02 C4 0B
[12.0052 s] rs485 ← 01 03 04 00 2A 00 19 1A 31

Bytes are grouped into frames and stamped with simulated time; a port that carries text shows text. serial read rs485 shows what went over the port since the last read. To use your own tools, open the port as the session starts, or later from the shell:

hardlabs -s acme/sensor-board --serial rs485=/tmp/ttyUSB0
my-bus-tool --device /tmp/ttyUSB0
You writeWhat you get
--serial rs485a socket://127.0.0.1:<port> address, for anything built on pyserial
--serial rs485=tcp:5000the same, on a port you choose
--serial rs485:ptya device file the system names (/dev/ttys004), opened like a USB serial adapter
--serial rs485=/tmp/ttyUSB0a device file at the path you choose
serial open rs485 [path | tcp:<n> | --pty]the same, from the shell; serial close rs485 closes it
  • Write a whole path. /dev/ttyUSB0 needs root, as in a CI container; /tmp/ttyUSB0 works anywhere. The CLI never replaces a real device or file, and removes its link when the session ends.
  • Device files need macOS or Linux, and Python 3 on your computer. On Windows, use a socket:// port.
  • A port keeps its address when the board restarts, and what your tool writes meanwhile is sent once the board is back. Bytes pass through unchanged both ways. serial portslists the board's ports.

Tests you can rerun

A scenario file is a test flow you'd otherwise click through by hand: work the board's controls, type into the firmware's shell, wait, and check what comes back. This one runs as written on the demo board:

demo.scenario.yaml
simulation: hardlabs/demo-board
setup:
  - expect_console: temp                  # every case boots the board afresh
cases:
  - name: overheat raises the alarm
    steps:
      - do: temperature-sensor-mcp9808.overheat-75-c
      - expect_console: ALARM
        within: 5s                        # simulated seconds
      - expect: alert-pin
        equals: true
      - do: button.sw1
      - expect_console: alarm acknowledged
$ hardlabs run demo.scenario.yaml
Starting hardlabs/demo-board@rev-a …
✓ overheat raises the alarm  1.5 s simulated, 4.9 s
1 passed
StepWhat it does
do: <control>, values:work a control, named as the shell's controls command lists it
send: <line>type a line into the firmware's shell
wait: <time>let simulated time pass: 2.5s, 500ms, 2m
expect_console: <text or list>, within:wait for each piece of text in order (up to 30 simulated seconds by default)
expect: <reading>, between: [low, high] or equals:check a value a panel shows, now
  • hardlabs run --list -s <simulation> prints the controls and readings a scenario can name. Every name is checked before any case runs.
  • -f build/app.elf runs the cases on your build; --junit report.xml writes results CI services show as tests.
  • Exit status: 0 every case passed, 1 a check failed, 2 the file doesn't fit the board, 3 a case couldn't run.

Debug with GDB

hardlabs -s acme/sensor-board -f build/zephyr/zephyr.elf --gdb

# in another terminal
arm-none-eabi-gdb build/zephyr/zephyr.elf -ex "target remote 127.0.0.1:3333"

Or type gdb in a running shell. The CLI prints the exact GDB command for your ELF and a launch.json entry for VS Code with Cortex-Debug. Symbols come from your local ELF, so nothing extra is uploaded.

Any GDB for your processor works. The Arm GNU Toolchain has arm-none-eabi-gdb for macOS, Linux and Windows; on Debian and Ubuntu, sudo apt install gdb-multiarch works too. In WSL, VS Code's WSL extension runs the debugger inside WSL, next to the CLI.

  • Connecting halts the CPU. While the debugger holds it, simulated time stands still: timers, peripherals and the console do not move under a breakpoint.
  • When GDB detaches or quits, the board keeps running.
  • monitor help lists the board commands GDB can send, such as monitor press <button>.
  • One debugger at a time per session.

Use it from a coding agent

hardlabs mcp gives Claude Code, Codex or any other MCP client access to your simulations. The agent can start a board, change it, read the firmware's console and check each model's scope while it works on your firmware. Sign in once with hardlabs login, then:

Claude Code
claude mcp add hardlabs -- npx -y hardlabs mcp
Codex · ~/.codex/config.toml
[mcp_servers.hardlabs]
command = "npx"
args = ["-y", "hardlabs", "mcp"]
Cursor · ~/.cursor/mcp.json (or .cursor/mcp.json in your repo)
{
  "mcpServers": {
    "hardlabs": { "command": "npx", "args": ["-y", "hardlabs", "mcp"] }
  }
}
VS Code · .vscode/mcp.json
{
  "servers": {
    "hardlabs": { "type": "stdio", "command": "npx", "args": ["-y", "hardlabs", "mcp"] }
  }
}

On Windows (not WSL), an agent can't start npx by itself: put cmd /c in front of it.

Claude Code on Windows
claude mcp add hardlabs -- cmd /c npx -y hardlabs mcp
Codex on Windows
[mcp_servers.hardlabs]
command = "cmd"
args = ["/c", "npx", "-y", "hardlabs", "mcp"]

If the board is already running on your account, say open on the website, the agent joins it as it is rather than restarting it. Boards the agent started stop when it exits; boards it joined keep running. With a simulation pinned in hardlabs.json, the agent starts that one by default.

Build a simulation from your design files

hardlabs create                                   # in your board or firmware repo
hardlabs create hw/ --firmware build/zephyr/zephyr.elf

hardlabs create finds your netlist (required), BOM, schematic, datasheets and firmware in the directory. It shows you what it picked and asks before uploading anything. HardLabs then builds a simulation of the board, and you can follow the build in your terminal. With firmware, it also runs your firmware on the board and checks every part against it (usually 5–25 minutes). Without firmware, each part gets a model checked against its datasheet (usually 5–20 minutes).

When the build finishes, the new simulation is pinned in hardlabs.json, so plain hardlabs opens it. You can build up to 3 simulations a day. Run hardlabs --help to see every flag.

If something is wrong

You seeWhat to do
No simulations have been shared with you yetRun hardlabs whoami. If the e-mail address is not the one your board was shared with, run hardlabs logout, then sign in with that address. If it is the right address, tell us and we will check the share.
an account with no e-mail on recordYou signed in somewhere other than hardlabs.io. Sign in on hardlabs.io itself, then run hardlabs login again.
not logged inRun hardlabs login, or check HARDLABS_TOKEN if you set one.
hardlabs: unknown command "whoami"Your CLI is older than the command. Run npm install -g hardlabs@latest.
is not an ELF filePass the ELF from your build (zephyr.elf, firmware.elf), not a .hex or .bin.
no firmware consoleThe board started, but this firmware has no console the simulation can attach to. The panels still update.

Usage records

The CLI, including hardlabs mcp, sends usage records to HardLabs: the commands, shell lines and MCP tools you use, with their options, how they end and how long they take, plus your CLI, OS and Node.js versions. File contents are never sent, file paths go only as file names, and options that look like secrets (tokens, passwords, keys) are left out. When you are logged in, records are tied to your account; details are in the privacy policy. Turn them off with hardlabs telemetry off, HARDLABS_TELEMETRY=0 or DO_NOT_TRACK=1.

Still stuck? Reply to your onboarding e-mail or write to us through the pilot form, and include the output of hardlabs whoami and hardlabs --version.