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.
First ten minutes
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 hardlabsCheck 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 loginThis 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 whoamiThis 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 ASimulations are named owner/project@version. You can type less than the full name:
| You type | You get |
|---|---|
| acme/sensor-board@v1.2.0 | exactly that version |
| acme/sensor-board | its latest published version |
| sensor-board | the 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
hardlabs -s hardlabs/demo-boardhardlabs -s acme/sensor-boardhardlabs -s acme/sensor-board -f build/zephyr/zephyr.elfhardlabs -s acme/sensor-board \
-f build/bootloader.bin@0x08000000 -f build/app.bin@0x08010000The 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) |
| shortcuts | firmware commands this board suggests |
| console [n] | the last n lines of the firmware's console |
| follow on|off | stream 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) |
| memory | the board's memory chips: EEPROM, F-RAM, SPI NOR (see below) |
| restart | power-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) |
| quit | stop the simulation |
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 goesEach 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-41Your 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 sPin a board revision for your team
Put a hardlabs.json at the root of your firmware repository:
{ "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:
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=0x0002A 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 write | What goes in |
|---|---|
| U7=settings.bin | the file, from the chip's first byte |
| U7:0x100=calibration.bin | the file, from offset 0x100 |
| U7:0x40=0x00010203 | these bytes |
| U9=erased | 0xFF from the offset to the end, as erased flash |
| U7:0x0=fill:0x00:64 | 64 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 holdsnvm/ 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 | |
|---|---|
| memory | the 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 |
| restart | power-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 31Bytes 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 write | What you get |
|---|---|
| --serial rs485 | a socket://127.0.0.1:<port> address, for anything built on pyserial |
| --serial rs485=tcp:5000 | the same, on a port you choose |
| --serial rs485:pty | a device file the system names (/dev/ttys004), opened like a USB serial adapter |
| --serial rs485=/tmp/ttyUSB0 | a 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:
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| Step | What 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 mcp add hardlabs -- npx -y hardlabs mcp[mcp_servers.hardlabs]
command = "npx"
args = ["-y", "hardlabs", "mcp"]{
"mcpServers": {
"hardlabs": { "command": "npx", "args": ["-y", "hardlabs", "mcp"] }
}
}{
"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 mcp add hardlabs -- cmd /c npx -y hardlabs mcp[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.elfhardlabs 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 see | What to do |
|---|---|
| No simulations have been shared with you yet | Run 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 record | You signed in somewhere other than hardlabs.io. Sign in on hardlabs.io itself, then run hardlabs login again. |
| not logged in | Run 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 file | Pass the ELF from your build (zephyr.elf, firmware.elf), not a .hex or .bin. |
| no firmware console | The 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.