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:
--port 1883: the port your broker listens on (passed asMQTT_PORT).--timeout 2s: how long to wait for each expected network event.--start-timeout 5s: how long to wait for your broker to open its port.--verbose: show your broker's output even when the tests pass.--no-trace: do not print the network timeline under a failed test.
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:
--server URL- the
IOT_SERVERenvironment variable - the
iotbricks.jsonof your project (searched in the current folder and its parents) - the only server you are signed in to
- 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
0: the tests passed.1: a test or the build failed, or the server could not be reached.2: a usage or configuration problem (bad flag, not signed in, invalid project file).
When something goes wrong
- You are not signed in to ...: run the
iotbricks initcommand of the getting-started page, oriotbricks login --server <url>on another computer. - This setup link is unknown, expired or already used: reload the getting-started page and copy the new command.
- The go line of go.mod is too new: the test servers build with a fixed Go version, shown on the
getting-started page. Lower it with
go mod edit -go=<that version>. - Your project is too large: the limit is 5 MiB compressed, 20 MiB of content and 2000 files. Remove build outputs and large files.
- The tests cannot reach your broker locally: check it listens on
MQTT_PORT, and that no other program (an old broker) already holds port 1883.