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.
• A simulation to run. 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.

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, 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

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

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

4. Run your firmware

hardlabs -s acme/sensor-board

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

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. Pass the ELF from your build, not a .hex or .bin. Images can be up to 64 MB.

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:

hardlabs> status              # what the board looks like now
hardlabs> controls            # what you can change
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

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.

Pin 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.

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 localhost: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.

• 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"]

Sessions the agent starts stop when the agent exits.

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

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.