CLI Reference

This document contains the help content for the zelos command-line program.

Command Overview:

• zelos↴
• zelos status↴
• zelos login↴
• zelos logout↴
• zelos actions↴
• zelos actions list↴
• zelos actions execute↴
• zelos actions schema↴
• zelos actions tui↴
• zelos agent↴
• zelos agent info↴
• zelos agent settings↴
• zelos agent settings set-data-retention↴
• zelos agent settings set-log-retention↴
• zelos agent settings set-dev-mode↴
• zelos agent settings set-memory-limit↴
• zelos extensions↴
• zelos extensions list↴
• zelos extensions install↴
• zelos extensions install-local↴
• zelos extensions start↴
• zelos extensions stop↴
• zelos extensions reinstall↴
• zelos extensions uninstall↴
• zelos extensions check-updates↴
• zelos extensions update↴
• zelos extensions info↴
• zelos extensions config↴
• zelos extensions create↴
• zelos live↴
• zelos live signals↴
• zelos live query↴
• zelos live watch↴
• zelos live export↴
• zelos live demo↴
• zelos trace↴
• zelos trace info↴
• zelos trace signals↴
• zelos trace query↴
• zelos trace merge↴
• zelos update↴
• zelos version↴
• zelos completions↴

zelos

Use the Zelos command line interface (CLI) to interact with the Zelos App, Zelos Agent, or directly with Zelos Cloud.

Connect to your agent, query live signals, manage extensions, inspect trace files, and more — all from the command line.

Usage: zelos [OPTIONS] <COMMAND>

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

Subcommands:

• status — Print Zelos system status
• login — Login to Zelos Cloud
• logout — Logout from Zelos Cloud
• actions — List, execute, and inspect agent actions
• agent — Inspect and configure the Zelos agent
• extensions — Manage Zelos Agent extensions
• live — Interact with live agent data
• trace — Trace file operations
• update — Update the Zelos CLI to the latest version
• version — Print version
• completions — Generate or install shell completions

Options:

• -q, --quiet — Disable logging to console
• -v, --verbose — Log to console, with increasing verbosity

zelos status

Print Zelos system status (agent, cloud, and app connectivity).

Usage: zelos status

Examples:

zelos status

zelos login

Login to Zelos Cloud using the OAuth2 device authorization flow.

Opens a browser to authenticate and stores credentials in the system keyring.

Usage: zelos login [OPTIONS]

Examples:

zelos login
zelos login --device-name my-laptop

Options:

• -d, --device-name <DEVICE_NAME> — The device name (default: hostname)

zelos logout

Logout from Zelos Cloud and remove stored credentials from the system keyring.

Usage: zelos logout

Examples:

zelos logout

zelos actions

List, execute, and inspect agent actions.

Actions are remote procedures registered by extensions running on the Zelos Agent. Use these commands to discover available actions, view their parameter schemas, and execute them with JSON parameters.

Usage: zelos actions [OPTIONS] <COMMAND>

Subcommands:

• list — List all available actions
• execute — Execute an action
• schema — Get the schema for an action
• tui — Interactive TUI for browsing and executing actions

Options:

• --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300

zelos actions list

List all available actions

Usage: zelos actions list [OPTIONS]

Examples:

zelos actions list
zelos actions list --json

Options:

• --json — Output in JSON format

zelos actions execute

Execute an action, optionally passing parameters as JSON.

Usage: zelos actions execute [OPTIONS] <ACTION>

Examples:

zelos actions execute "Get Status"
zelos actions execute "Read Registers" --params '{"address": 0, "count": 10}'
zelos actions execute "Configure" --params-file config.json

Arguments:

• <ACTION> — Action path (e.g. "service/action")

Options:

• -p, --params <PARAMS> — JSON parameters
• --params-file <PARAMS_FILE> — Read parameters from a JSON file
• -t, --timeout <TIMEOUT> — Timeout in milliseconds

zelos actions schema

Show the parameter schema for an action.

Usage: zelos actions schema <ACTION>

Examples:

zelos actions schema "Read Registers"

Arguments:

• <ACTION> — Action path (e.g. "service/action")

zelos actions tui

Interactive TUI for browsing and executing actions

Usage: zelos actions tui

zelos agent

Inspect and configure the Zelos Agent.

View agent health, system info, and current settings. Modify data retention, log retention, developer mode, and memory limits.

Usage: zelos agent [OPTIONS] <COMMAND>

Subcommands:

• info — Show agent health, system info, and current settings
• settings — View or modify agent settings

Options:

• --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300

zelos agent info

Show agent health, system info, and current settings

Usage: zelos agent info [OPTIONS]

Examples:

zelos agent info
zelos agent info --json

Options:

• --json — Output in JSON format

zelos agent settings

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

Usage: zelos agent settings [OPTIONS] [COMMAND]

Examples:

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

Subcommands:

• set-data-retention — Set data retention period (e.g. "1h", "24h", "7d", "none" to disable)
• set-log-retention — Set log retention period (e.g. "1h", "24h", "7d", "none" to disable)
• set-dev-mode — Enable or disable developer mode
• set-memory-limit — Set memory limit (e.g. "512MB", "2GB", "none" to disable)

Options:

• --json — Output in JSON format (for viewing)

zelos agent settings set-data-retention

Set data retention period (e.g. "1h", "24h", "7d", "none" to disable)

Usage: zelos agent settings set-data-retention <VALUE>

Arguments:

• <VALUE> — Duration string (e.g. "1h", "24h", "7d") or "none" to disable

zelos agent settings set-log-retention

Set log retention period (e.g. "1h", "24h", "7d", "none" to disable)

Usage: zelos agent settings set-log-retention <VALUE>

Arguments:

• <VALUE> — Duration string (e.g. "1h", "24h", "7d") or "none" to disable

zelos agent settings set-dev-mode

Enable or disable developer mode

Usage: zelos agent settings set-dev-mode <VALUE>

Arguments:

• <VALUE> — true or false

Possible values: true, false

zelos agent settings set-memory-limit

Set memory limit (e.g. "512MB", "2GB", "none" to disable)

Usage: zelos agent settings set-memory-limit <VALUE>

Arguments:

• <VALUE> — Memory limit string (e.g. "512MB", "2GB") or "none" to disable

zelos extensions

Manage Zelos Agent extensions.

Install, start, stop, update, and inspect extensions running on the agent. Extensions are plugins that add data sources, actions, and custom behavior.

Usage: zelos extensions [OPTIONS] <COMMAND>

Subcommands:

• list — List all installed extensions
• install — Install an extension from the marketplace
• install-local — Install an extension from a local directory (requires agent --dev-mode)
• start — Start an extension
• stop — Stop an extension
• reinstall — Reinstall an extension's environment without removing config
• uninstall — Uninstall an extension
• check-updates — Check for available updates for all installed extensions
• update — Update an extension to a specific or latest version
• info — Show detailed information about an installed extension
• config — View configuration schema and last saved config for an extension
• create — Create a new extension from a template

Options:

• --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300

zelos extensions list

List all installed extensions

Usage: zelos extensions list [OPTIONS]

Examples:

zelos extensions list
zelos extensions list --json

Options:

• --json — Output in JSON format

zelos extensions install

Install an extension from the marketplace (e.g. acme/canbus-listener).

Usage: zelos extensions install <NAME> [VERSION]

Examples:

zelos extensions install acme/canbus-listener
zelos extensions install acme/canbus-listener 0.2.0

Arguments:

• <NAME> — Extension name in 'publisher/name' format
• <VERSION> — Extension version tag (e.g., "0.1.0", "latest")

Default value: latest

zelos extensions install-local

Install an extension from a local directory (requires agent --dev-mode)

Usage: zelos extensions install-local <PATH>

Examples:

zelos extensions install-local ./my-extension

Arguments:

• <PATH> — Path to extension source directory containing extension.toml

zelos extensions start

Start an extension

Usage: zelos extensions start [OPTIONS] <ID>

Examples:

zelos extensions start my-extension
zelos extensions start my-extension --config '{"demo": true}'
zelos extensions start my-extension --config-file config.json

Arguments:

• <ID> — Extension ID to start

Options:

• --config-file <CONFIG_FILE> — Path to a configuration file to pass to the extension
• --config <CONFIG> — A string of configuration to pass to the extension

zelos extensions stop

Stop an extension

Usage: zelos extensions stop <ID>

Examples:

zelos extensions stop my-extension

Arguments:

• <ID> — Extension ID to stop

zelos extensions reinstall

Reinstall an extension's environment without removing config

Usage: zelos extensions reinstall <ID>

Examples:

zelos extensions reinstall my-extension

Arguments:

• <ID> — Extension ID to reinstall

zelos extensions uninstall

Uninstall an extension

Usage: zelos extensions uninstall <ID>

Examples:

zelos extensions uninstall my-extension

Arguments:

• <ID> — Extension ID to uninstall

zelos extensions check-updates

Check for available updates for all installed extensions

Usage: zelos extensions check-updates

Examples:

zelos extensions check-updates

zelos extensions update

Update an extension to a specific or latest version

Usage: zelos extensions update <ID> [VERSION]

Examples:

zelos extensions update my-extension
zelos extensions update my-extension 0.3.0

Arguments:

• <ID> — Extension ID to update
• <VERSION> — Target version tag (e.g., "0.2.0", "latest")

Default value: latest

zelos extensions info

Show detailed information about an installed extension

Usage: zelos extensions info [OPTIONS] <ID>

Examples:

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

Arguments:

• <ID> — Extension ID (e.g., "acme/canbus-listener")

Options:

• --json — Output in JSON format

zelos extensions config

View configuration schema and last saved config for an extension

Usage: zelos extensions config [OPTIONS] <ID>

Examples:

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

Arguments:

• <ID> — Extension ID

Options:

• --json — Output in JSON format

zelos extensions create

Create a new extension from a template

Usage: zelos extensions create [OPTIONS] <NAME>

Examples:

zelos extensions create my-new-extension
zelos extensions create my-new-extension --author "Jane Doe" --description "My extension"

Arguments:

• <NAME> — Project name for the new extension

Options:

• -o, --output <OUTPUT> — Output directory (default: current directory)
• --author <AUTHOR> — Author name
• --email <EMAIL> — Author email
• --github <GITHUB> — GitHub handle
• --description <DESCRIPTION> — Project description
• --python-version <PYTHON_VERSION> — Python version

Default value: 3.11

zelos live

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

List signals, query values, stream live updates, export traces, or publish mock demo data for testing.

Usage: zelos live [OPTIONS] <COMMAND>

Subcommands:

• signals — List available signals from connected agents
• query — Query latest signal values from live agent data
• watch — Stream live signal values from connected agents
• export — Export live trace data from connected agents to a .trz file
• demo — Publish mock device data to the agent for testing

Options:

• --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300

zelos live signals

List available signals from connected agents

Usage: zelos live signals [OPTIONS]

Examples:

zelos live signals
zelos live signals --json

Options:

• --json — Output in JSON format

zelos live query

Query latest signal values from live agent data.

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.

Usage: zelos live query [OPTIONS] --signals <SIGNALS>

Examples:

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

Options:

• -s, --signals <SIGNALS> — Signal patterns to query (e.g. '*/bus0/BMS_message/status.battery_level')
• -l, --last <LAST> — Time span preset (e.g. 30s, 1m, 5m, 10m, 30m, 1h)

Default value: 30s

Possible values:

• 30s: Last 30 seconds
• 1m: Last 1 minute
• 5m: Last 5 minutes
• 10m: Last 10 minutes
• 30m: Last 30 minutes
• 1h: Last 1 hour
• 2h: Last 2 hours
• 6h: Last 6 hours
• 12h: Last 12 hours

• 24h: Last 24 hours

• --start <START> — Explicit start time (ISO 8601, e.g. 2025-01-01T00:00:00Z)

• --end <END> — Explicit end time (ISO 8601, e.g. 2025-01-01T01:00:00Z)
• -a, --agents <AGENTS> — Agent addresses to query (default: all connected agents)
• -f, --format <FORMAT> — Output format

Default value: table

Possible values:

• table: Tab-separated table (human readable)
• json: JSON output
• csv: Comma-separated values

zelos live watch

Stream live signal values, refreshing periodically. Press Ctrl+C to stop.

Usage: zelos live watch [OPTIONS]

Examples:

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

Options:

• -i, --interval <INTERVAL> — Refresh interval

Default value: 1s * -n, --count <COUNT> — Number of refreshes (0 = unlimited, until Ctrl+C)

Default value: 0

zelos live export

Export live trace data from connected agents to a .trz file

Usage: zelos live export [OPTIONS]

Examples:

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

Options:

• -o, --output <OUTPUT> — Output file path (default: trace_.trz in current directory)
• -l, --last <LAST> — Time span preset (e.g. 30s, 1m, 5m, 10m, 30m, 1h, 2h, 6h, 12h, 24h)

Default value: 1h

Possible values:

• 30s: Last 30 seconds
• 1m: Last 1 minute
• 5m: Last 5 minutes
• 10m: Last 10 minutes
• 30m: Last 30 minutes
• 1h: Last 1 hour
• 2h: Last 2 hours
• 6h: Last 6 hours
• 12h: Last 12 hours

• 24h: Last 24 hours

• --start <START> — Explicit start time (ISO 8601, e.g. 2025-01-01T00:00:00Z)

• --end <END> — Explicit end time (ISO 8601, e.g. 2025-01-01T01:00:00Z)
• -a, --agents <AGENTS> — Agent addresses to export from (default: all connected agents)
• -f, --force — Overwrite output file if it exists

zelos live demo

Publish mock device data to the agent for testing.

Simulates BMS, DCDC, inverter, and sensor devices at various frequencies. Press Ctrl+C to stop (or use --duration).

Usage: zelos live demo [OPTIONS]

Examples:

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

Options:

• -d, --device <DEVICE> — Mock device types to simulate

Default value: all

Possible values:

• all: All mock devices (BMS + DCDC + Inverter + Sensor)
• bms: Battery Management System (1 Hz)
• dcdc: DC-DC Converter (1 Hz)
• inverter: Grid/Battery Inverter (10 Hz)

• sensor: Generic Sensors & System Events (100 Hz)

• --duration <DURATION> — Duration to run (e.g. 30s, 5m, 1h). Omit to run until Ctrl+C

zelos trace

Offline operations on .trz trace files.

Inspect metadata, list signals, query signal data, and merge multiple traces into a single file.

Usage: zelos trace <COMMAND>

Subcommands:

• info — Show detailed metadata for a .trz trace file
• signals — List available signals in a trace file
• query — Query signal data from a .trz trace file
• merge — Merge multiple .trz files into a single trace

zelos trace info

Show metadata for a trace file including time range, data segments, tables, and row counts.

Usage: zelos trace info [OPTIONS] <FILE>

Examples:

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

Arguments:

• <FILE> — Path to the .trz trace file

Options:

• --json — Output in JSON format

zelos trace signals

List available signals in a trace file

Usage: zelos trace signals [OPTIONS] <FILE>

Examples:

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

Arguments:

• <FILE> — Path to a .trz trace file

Options:

• --json — Output in JSON format

zelos trace query

Query signal data from a .trz trace file

Usage: zelos trace query [OPTIONS] --signals <SIGNALS> <FILE>

Examples:

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

Arguments:

• <FILE> — Path to the .trz trace file

Options:

• -s, --signals <SIGNALS> — Signal patterns to query (e.g. '*/bus0/BMS_message/status.battery_level')
• -n, --limit <LIMIT> — Maximum number of rows to return (0 = unlimited)

Default value: 100 * -f, --format <FORMAT> — Output format

Default value: table

Possible values:

• table: Tab-separated table (human readable)
• json: JSON output
• csv: Comma-separated values

zelos trace merge

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

Usage: zelos trace merge [OPTIONS] --output <OUTPUT> <INPUTS>...

Examples:

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

Arguments:

• <INPUTS> — Input .trz files or directories containing .trz files

Options:

• -o, --output <OUTPUT> — Output file path
• -f, --force — Overwrite output if it exists
• --keep-partial — Keep partial output file on error (default: clean up)

zelos update

Self-update the CLI binary to the latest (or a specific) version.

Downloads the release from the Zelos CDN, verifies the SHA-256 checksum, and replaces the current binary in place. Shell completions are automatically reinstalled after a successful update.

Usage: zelos update [OPTIONS]

Examples:

zelos update                        # update to latest
zelos update --version 0.1.2        # install specific version
zelos update --force                # skip confirmation prompt

Options:

• --version <VERSION> — Install a specific version instead of latest
• -f, --force — Skip confirmation prompt

zelos version

Print the CLI version and build target.

Usage: zelos version

Examples:

zelos version

zelos completions

Generate or install shell completions for bash, zsh, fish, PowerShell, or elvish.

If no shell is specified, the current shell is auto-detected from $SHELL. Use --install to write completions directly to the appropriate system directory. Without --install, completions are printed to stdout for manual piping or inspection.

Usage: zelos completions [OPTIONS] [SHELL]

Examples:

zelos completions bash --install    # install to system dir
zelos completions zsh --install     # install for zsh
zelos completions fish --install    # install for fish
zelos completions bash              # print to stdout
zelos completions                   # auto-detect shell, print to stdout

Completions are also auto-installed during zelos update and the installer script.

Arguments:

• <SHELL> — Shell to generate completions for (auto-detected if omitted)

Possible values: bash, elvish, fish, powershell, zsh

Options:

• --install — Install completions into the appropriate system directory