CLI

senzor-cli is the headless runner. For a guided introduction, see Running headless.

SynopsisCopy Anchor Link

senzor-cli [OPTIONS] validate <PROJECT>
senzor-cli [OPTIONS] run <PROJECT> [--only <ID>[,<ID>…]] [--duration <DURATION>]
senzor-cli help [COMMAND]
senzor-cli --version

<PROJECT> is the path of a project file.

Global optionsCopy Anchor Link

-v and -h work before or after the command; -V only before it.

validateCopy Anchor Link

senzor-cli validate <PROJECT>

Loads and validates a project and prints every problem. It resolves the broker settings as run does: it reads the environment variable named in password_env and the TLS files, relative to the folder of the project file. It does not connect to the broker.

• Valid: prints <PROJECT>: OK (<n> devices, <m> instances) to stdout and exits with 0. A count of 1 takes the singular, for example examples/headless-ci.toml: OK (1 device, 10 instances).
• Invalid: prints each problem to stderr as <PROJECT>: <location>: <message> and exits with 2. See Validation errors.

runCopy Anchor Link

senzor-cli run <PROJECT> [--only <ID>[,<ID>…]] [--duration <DURATION>]

run does the following:

1. Loads and validates the project like validate. If there is any problem, it prints the problems and exits with 2 without starting anything.
2. Selects the devices: those listed in --only, or, without --only, every device with autostart = true.
3. Starts every instance of the selected devices. Each one connects to the broker with its own client.
4. Waits for Ctrl+C, SIGTERM (on Linux and macOS), or the end of --duration.
5. Logs shutting down and stops the instances gracefully: each online instance publishes its availability offline message, if its template has availability, and disconnects. After 2 seconds, connections that are still open are dropped.
6. Exits with 0.

Exit codesCopy Anchor Link

run exits with 0 even when instances could not connect or failed while running.

MessagesCopy Anchor Link

senzor-cli prints these errors to stderr itself, before anything runs.

Invalid arguments are reported by the argument parser and exit with 2, for example:

error: invalid value '30' for '--duration <DURATION>': time unit needed, for example 30sec or 30ms

OutputCopy Anchor Link

• stdout gets only the OK line of validate, and the output of --help and --version.
• stderr gets everything else: problems, errors and the log.

LoggingCopy Anchor Link

The log goes to stderr, one line per event:

2026-10-15T15:53:14.229242Z  INFO senzor_core::engine::state: reconnecting: I/O: Connection refused (os error 111) instance=kitchen attempt=1

The time is UTC. Lines about an instance carry instance=<instance ID>. Other libraries, such as the MQTT client, log only warnings and errors unless RUST_LOG says otherwise.

When the broker refuses a connection, the reason is broker refused the connection: <code>, where <code> is one of RefusedProtocolVersion, BadClientId, ServiceUnavailable, BadUserNamePassword or NotAuthorized.

Environment variablesCopy Anchor Link