IoT Bricks Try challenge Blog Sign in

The iotbricks CLI

iotbricks sends your project to the platform, runs the tests for a stage and prints what to fix. The free stages also run entirely on your computer.

Install

curl -fsSL https://iotbricks.dev/install.sh | sh

The installer downloads the build for your system (macOS or Linux, amd64 or arm64), checks its SHA-256 checksum and puts it in ~/.local/bin, never with sudo. Set IOT_INSTALL_DIR to install somewhere else. Windows has no installer yet.

Commands

iotbricks init <setup link> [folder]

Creates your project from the personal command on the getting-started page:

iotbricks init https://iotbricks.dev/p/<code> iotbricks-mqtt-go

It signs this computer in, then creates the folder with a starter project and an iotbricks.json file. The link works once and expires after an hour: reload the getting-started page for a new one. The folder must not exist yet, or be empty.

iotbricks ping [--server URL]

Checks the whole setup: the project file, the server and your login. The getting-started page turns green when the ping arrives.

iotbricks test [--stage N] [--server URL] [--no-trace]

Run it from your project folder (or any folder inside it). It packs the project, sends it to the platform, which builds and runs it in a sandbox, and prints the results live. They also appear on the stage page. Without --stage, it tests the next stage you have not passed. A run replays every stage from 1 to N, so an earlier stage that broke fails the run.

Under a failed test, a timeline shows what happened on the network, in order: each packet the tester's clients sent (→) and your broker answered (←), the waits where nothing came (…), and the closed connections (✕), with the time since the test started and the first bytes in hex:

what happened (time since the test started):
    +0 ms  sensor  →  CONNECT (client id "sensor", clean session, keep-alive 60 s)   10 12 00 04 …
    +1 ms  sensor  ←  CONNACK (code 0, accepted)   20 02 00 00
    +2 ms  sensor  →  PINGREQ   C0 00
 +2004 ms  sensor  …  nothing received for 2000 ms

The stage page shows the same timeline. --no-trace leaves it out of the terminal.

iotbricks test local --stage N --run "<command>"

Runs a free stage on your own computer, with no account and no network:

iotbricks test local --stage 1 --run ./iotbricks-mqtt-go

--run is the command that starts your broker; it is run with sh -c. Your broker must listen on the port in the MQTT_PORT environment variable. Options:

Only the free stages run locally; the others need iotbricks test.

iotbricks login [--server URL] [--label NAME] and iotbricks logout [--server URL]

Sign in on another computer with GitHub (the CLI shows a code to enter on github.com), or sign out and revoke this computer's token. On your first computer, iotbricks init already signed you in.

Which server it talks to

Each command picks the server in this order:

  1. --server URL
  2. the IOT_SERVER environment variable
  3. the iotbricks.json of your project (searched in the current folder and its parents)
  4. the only server you are signed in to
  5. the default

If you are signed in to several servers and nothing else says which one, the CLI stops and asks for --server. Only https is accepted, except for your own machine.

The project file: iotbricks.json

{"server": "https://iotbricks.dev", "course": "mqtt", "language": "go"}

It ties the folder to its server, course and language. It holds no secret, so you can commit it. Your login lives in ~/.config/iotbricks/credentials (or under $XDG_CONFIG_HOME), never in the project. IOT_TOKEN, when set, is used instead of the saved login; a project file never decides where that token is sent.

Exit codes

When something goes wrong