CLI Reference¶

Complete command reference for the zelos CLI. For installation instructions, see the install guide.

Global Options¶

Flag	Description
`-q, --quiet`	Disable logging to console
`-v, --verbose`	Increase log verbosity (repeat for more: `-vv`)
`-h, --help`	Print help
`-V, --version`	Print version

Simple Commands¶

Command	Description
`zelos status`	Print Zelos system status (agent, cloud, app connectivity)
`zelos login`	Login to Zelos Cloud (OAuth2 device flow)
`zelos logout`	Logout from Zelos Cloud
`zelos update`	Self-update the CLI to the latest version
`zelos version`	Print CLI version and build target

trace¶

Offline .trz trace file operations.

zelos trace <subcommand>

trace info¶

Show metadata for a trace file (time range, segments, tables, row counts).

zelos trace info recording.trz
zelos trace info recording.trz --json

trace signals¶

List all signals in a trace file.

zelos trace signals recording.trz
zelos trace signals recording.trz --json

trace query¶

Query signal data from a trace file.

zelos trace query recording.trz -s '*/bus0/BMS_message/status.battery_level'
zelos trace query recording.trz -s '*/*.*' --format json -n 50

Flag	Description
`-s, --signals`	Signal patterns to query (required, repeatable)
`-n, --limit`	Max rows to return (default: 100, 0 = unlimited)
`-f, --format`	Output format: `table` (default), `json`, `csv`

trace merge¶

Merge multiple .trz files into a single trace. Accepts files and/or directories.

zelos trace merge trace1.trz trace2.trz -o combined.trz
zelos trace merge ./traces/ -o combined.trz --force

Flag	Description
`-o, --output`	Output file path (required)
`-f, --force`	Overwrite output if it exists
`--keep-partial`	Keep partial output file on error

live¶

Interact with live agent data. All subcommands connect to the agent via gRPC.

zelos live [--host <HOST>] <subcommand>

Flag	Default	Description
`--host`	`localhost:2300`	Agent gRPC endpoint

live signals¶

List all signals the agent is currently receiving.

zelos live signals
zelos live signals --json

live query¶

Query the latest values for specific signals.

Signal format: */source/message.signal — the leading * is a wildcard for the data segment ID, but source, message, and signal must be exact names (no wildcards). Use live signals to discover available signal names.

zelos live query -s '*/iot_gateway/temperature.sensor1' --last 1m
zelos live query -s '*/bus0/BMS_status.battery_level' --format json

Flag	Description
`-s, --signals`	Signal patterns to query (required, repeatable)
`-l, --last`	Time span preset: `30s` (default), `1m`, `5m`, `10m`, `30m`, `1h`, `2h`, `6h`, `12h`, `24h`
`--start / --end`	Explicit ISO 8601 time range (instead of `--last`)
`-a, --agents`	Agent addresses to query (default: all connected)
`-f, --format`	Output format: `table` (default), `json`, `csv`

live watch¶

Stream live signal values, refreshing periodically.

zelos live watch
zelos live watch -i 2s -n 10

Flag	Description
`-i, --interval`	Refresh interval (default: `1s`)
`-n, --count`	Number of refreshes (default: 0 = until Ctrl+C)

live export¶

Export live trace data to a .trz file.

zelos live export --last 5m -o capture.trz
zelos live export --start 2025-01-01T00:00:00Z --end 2025-01-01T01:00:00Z -o capture.trz

Flag	Description
`-o, --output`	Output file path (default: `trace_<timestamp>.trz`)
`-l, --last`	Time span preset: `1h` (default), `30s`, `1m`, `5m`, etc.
`--start / --end`	Explicit ISO 8601 time range (instead of `--last`)
`-a, --agents`	Agent addresses (default: all connected)
`-f, --force`	Overwrite output if it exists

live demo¶

Publish mock device data to the agent for testing.

zelos live demo
zelos live demo -d bms --duration 30s

Flag	Description
`-d, --device`	Device type: `all` (default), `bms`, `dcdc`, `inverter`, `sensor`
`--duration`	Run duration (e.g. `30s`, `5m`). Omit to run until Ctrl+C

actions¶

List, execute, and inspect agent actions.

zelos actions [--host <HOST>] <subcommand>

actions list¶

List all registered actions.

zelos actions list
zelos actions list --json

actions schema¶

Show the parameter schema for an action.

zelos actions schema "Read Registers"

actions execute¶

Execute an action, optionally passing parameters as JSON.

zelos actions execute "Get Status"
zelos actions execute "Read Registers" --params '{"address": 0, "count": 10}'

Flag	Description
`-p, --params`	JSON parameters as a string
`--params-file`	Read parameters from a JSON file

agent¶

Inspect and configure the Zelos agent.

zelos agent [--host <HOST>] <subcommand>

agent info¶

Show agent health, system info, and current settings.

zelos agent info
zelos agent info --json

Flag	Description
`--json`	Output in JSON format

agent settings¶

View or modify agent settings. Run without a subcommand to display current settings.

zelos agent settings
zelos agent settings --json
zelos agent settings set-data-retention 24h
zelos agent settings set-dev-mode true
zelos agent settings set-memory-limit 2GB

Subcommand	Description
`set-data-retention <value>`	Set data retention period (e.g. `1h`, `24h`, `7d`, `none`)
`set-log-retention <value>`	Set log retention period
`set-dev-mode <true\\|false>`	Enable or disable developer mode
`set-memory-limit <value>`	Set memory limit (e.g. `512MB`, `2GB`, `none`)

extensions¶

Manage Zelos Agent extensions.

zelos extensions [--host <HOST>] <subcommand>

Lifecycle¶

zelos extensions list
zelos extensions list --json
zelos extensions install acme/canbus-listener
zelos extensions install-local ./my-extension
zelos extensions start my-extension
zelos extensions start my-extension --config '{"demo": true}'
zelos extensions start my-extension --config-file config.json
zelos extensions stop my-extension
zelos extensions uninstall my-extension
zelos extensions reinstall my-extension

Subcommand	Description
`list`	List all installed extensions (`--json` for JSON output)
`install <id> [version]`	Install from marketplace (e.g. `acme/canbus-listener`)
`install-local <path>`	Install from local directory (requires `--dev-mode`)
`start <id>`	Start an extension (`--config` or `--config-file` to pass config)
`stop <id>`	Stop an extension
`uninstall <id>`	Uninstall an extension
`reinstall <id>`	Reinstall environment without removing config

Inspection¶

zelos extensions info local.my-extension
zelos extensions info local.my-extension --json
zelos extensions config local.my-extension
zelos extensions config local.my-extension --json

Subcommand	Description
`info <id>`	Show detailed info (version, state, PID, paths). `--json` for JSON output
`config <id>`	View config schema and last saved config. `--json` for JSON output

Updates & Scaffolding¶

zelos extensions check-updates
zelos extensions update my-extension
zelos extensions create

Subcommand	Description
`check-updates`	Check for available updates
`update <id>`	Update to latest or specific version
`create`	Scaffold a new extension from a template

Environment Variables¶

Variable	Description
`RUST_LOG`	Override log level (e.g. `RUST_LOG=debug zelos status`)

Files & Paths¶

Path	Description
`~/.zelos/bin/`	CLI binary location
`~/.zelos/`	Configuration directory
System keyring	Cloud credentials