Skip to content

CLI Reference

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

Command Overview:

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 extensions
  • live — Interact with live agent data
  • trace — Trace file operations
  • tools — Inspect and call Zelos agent tools (experimental, local dogfood only)
  • 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)
  • set-store-type — Set store type ("memory" or "disk"). Requires agent restart
  • set-store-path — Set disk store folder path. Requires agent restart
  • set-disk-limit — Set disk size limit (e.g. "10GB", "500MB", "none" to disable)
  • clear-store — Clear all data from the store (irreversible)
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 agent settings set-store-type

Set store type ("memory" or "disk"). Requires agent restart

Usage: zelos agent settings set-store-type <VALUE>

Arguments:
  • <VALUE> — "memory" for in-memory ArrowStore, "disk" for Parquet-backed disk store

zelos agent settings set-store-path

Set disk store folder path. Requires agent restart

Usage: zelos agent settings set-store-path <VALUE>

Arguments:
  • <VALUE> — Folder path, or "none" to use default

zelos agent settings set-disk-limit

Set disk size limit (e.g. "10GB", "500MB", "none" to disable)

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

Arguments:
  • <VALUE> — Disk limit string (e.g. "10GB", "500MB") or "none" to disable

zelos agent settings clear-store

Clear all data from the store (irreversible)

Usage: zelos agent settings clear-store

zelos extensions

Manage Zelos extensions.

Install, create, start, stop, update, and inspect Zelos extensions. Extensions can run as agent processes or app-hosted web extensions.

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 for development
  • package — Package an extension directory into a release archive
  • start — Start an agent extension
  • stop — Stop an agent extension
  • reinstall — Reinstall an agent 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
  • bump — Bump extension version in extension.toml (and package.json/package-lock.json/pyproject.toml if present)
  • 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 for development

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 package

Package an extension directory into a release archive

Usage: zelos extensions package [OPTIONS] <PATH>

Examples:

zelos extensions package ./my-extension
zelos extensions package ./my-extension --output ./dist
zelos extensions package ./my-extension --list
Arguments:
  • <PATH> — Path to the extension directory containing extension.toml
Options:
  • -o, --output <OUTPUT> — Output path or directory for the generated tar.gz archive
  • --list — List files that would be included in the package without creating an archive

zelos extensions start

Start an agent extension

Usage: zelos extensions start [OPTIONS] <ID>

Examples:

zelos extensions start local.my-extension
zelos extensions start local.my-extension --config '{"demo": true}'
zelos extensions start local.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 agent extension

Usage: zelos extensions stop <ID>

Examples:

zelos extensions stop local.my-extension
Arguments:
  • <ID> — Extension ID to stop

zelos extensions reinstall

Reinstall an agent extension's environment without removing config

Usage: zelos extensions reinstall <ID>

Examples:

zelos extensions reinstall local.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> — Installed extension ID (for example, "local.my-extension")
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 bump

Bump extension version in extension.toml (and package.json/package-lock.json/pyproject.toml if present)

Usage: zelos extensions bump [OPTIONS] <VERSION>

Examples:

zelos extensions bump 1.0.0
zelos extensions bump 2.0.0 --path ./my-extension
Arguments:
  • <VERSION> — New semver version (e.g., "1.2.3")
Options:
  • --path <PATH> — Extension directory (defaults to current directory)

Default value: .

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"
zelos extensions create my-app-extension --type app
zelos extensions create my-app-extension --type app --template react
zelos extensions create my-app-extension --type app --template wasm
zelos extensions create my-app-extension --type app --template-ref main

App templates (only meaningful with --type app, fetched from zeloscloud/zelos-extension-templates):

  • react React + bridge SDK; default for --type app.
  • wasm Vanilla TS + workers + COOP/COEP recipe.
Arguments:
  • <NAME> — Project name for the new extension
Options:
  • --type <TYPE> — Extension type: "agent" or "app"

Default value: agent

Possible values: agent, app

  • -o, --output <OUTPUT> — Output directory (default: current directory)
  • --author <AUTHOR> — Author name
  • --email <EMAIL> — Author email
  • --github <GITHUB> — GitHub handle
  • --description <DESCRIPTION> — Project description
  • --template <TEMPLATE> — App template variant. Only meaningful with --type app. Choices: react (default; React + ZelosAppProvider), wasm (TS + workers + COOP/COEP recipe)

Possible values:

  • react: React + ZelosAppProvider + bridge SDK. Default for --type app

  • wasm: Vanilla TS + WASM-friendly recipe (?worker&inline, COOP/COEP headers)

  • --template-ref <TEMPLATE_REF> — Template branch or tag override (default: latest stable tag)

  • --python-version <PYTHON_VERSION> — Python version

Default value: 3.11 * --no-setup — Skip post-create setup (dependency install, git init, local install)

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
  • latest — Query latest signal values via the agent's gRPC latest API (tests arrow_value path)
  • watch — Stream live signal values from connected agents
  • export — Export live trace data from connected agents to a .trz file
  • query-ts — Query timeseries data (M4 downsampled) and inspect Arrow IPC columns
  • check — Run a typed predicate check against the agent's live store
  • 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
  • --lookback <LOOKBACK> — Catalog freshness window for signal resolution (e.g. 30s, 5m, 1h). Default 60s, matching agent.latest()

Default value: 60s * --producers <PRODUCERS> — Producer addresses to consult for catalog resolution. Comma- separated list (e.g. localhost,otherhost). Default localhost — same as agent.latest(producers=("localhost",))

Default value: localhost

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. Accepts ISO 8601 (2025-01-01T00:00:00Z), a date (2025-01-01), a relative offset (-30s / -1.5m / +1h), now, a bare integer (epoch ns), or a bare decimal (epoch seconds)

  • --end <END> — Explicit end time. Same grammar as --start
  • -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 latest

Query the latest value for each signal via the agent's gRPC API.

Uses the LatestSignalValue response which includes both the legacy string value and the new Arrow IPC arrow_value field. Shows which path was used.

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

Examples:

zelos live latest -s '*/eth0/can_raw.data' -s '*/eth0/sensor_events.event_type'
Options:
  • -s, --signals <SIGNALS> — Signal patterns to query
  • -a, --agents <AGENTS> — Agent addresses (default: localhost)

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. Accepts ISO 8601 (2025-01-01T00:00:00Z), a date (2025-01-01), a relative offset (-30s / -1.5m / +1h), now, a bare integer (epoch ns), or a bare decimal (epoch seconds)

  • --end <END> — Explicit end time. Same grammar as --start
  • -a, --agents <AGENTS> — Agent addresses to export from (default: all connected agents)
  • -f, --force — Overwrite output file if it exists

zelos live query-ts

Query timeseries data using the M4 downsampling path (same as plot panels).

Shows column types, dictionary value tables, and sample data. Useful for verifying that string/binary columns are dictionary-encoded.

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

Examples:

zelos live query-ts -s '*/can_log/log.message' --last 30s
zelos live query-ts -s '*/can_log/log.message' --last 1m --width 200
Options:
  • -s, --signals <SIGNALS> — Signal patterns to query
  • -l, --last <LAST> — Time span preset

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

  • -w, --width <WIDTH> — Plot width for M4 downsampling (number of pixels)

Default value: 800 * -a, --agents <AGENTS> — Agent addresses to query (default: localhost)

zelos live check

Run a typed predicate check against the agent's live store

Usage: zelos live check [OPTIONS]

Examples:

zelos live check --lhs-signal '*/bus0/BMS_message/status.cell_voltage' --op gt --rhs=-1 --last 30s --temporal all
zelos live check --lhs-signal '*/bus1/inverter_status.mode' --op eq --rhs 'Grid-Tied' --last 30s --temporal any
zelos live check --suite checks.json
zelos live check --lhs-signal 'bus0/BMS_message/status.cell_voltage' --op lt --rhs 4.2 --producers localhost,otherhost
Options:
  • --lhs <LHS> — LHS literal — auto-typed: true/false -> bool, contains . -> float, numeric -> int, else string. Use --lhs=-1.5 for negative numbers. Mutually exclusive with --lhs-signal
  • --lhs-signal <LHS_SIGNAL> — LHS signal path (e.g. bus0/BMS_message/status.cell_voltage or */source/message.signal). Mutually exclusive with --lhs
  • --op <OP> — Comparison operator. Accepts gt|ge|lt|le|eq|ne, the symbolic aliases >, >=, <, <=, ==, != (quote in the shell to dodge redirection), the tolerance / integer ops (is_close, is_approximately, is_divisible_by), and the string / unary ops. Required for non-suite checks

Possible values: gt, ge, lt, le, eq, ne, is_close, is_approximately, is_divisible_by, is_empty, is_positive, is_not_positive, is_negative, is_not_negative, is_true, is_false, contains, starts_with, ends_with, is_in, is_not_in

  • --rhs <RHS> — RHS literal — same auto-typing rules as --lhs. Required for binary ops; rejected for unary ops. Use --rhs=-1.5 for negative numbers
  • --rhs-signal <RHS_SIGNAL> — RHS signal path for signal-vs-signal comparison. Must point at the same {source}/{message} event table as --lhs-signal (cross-table requires alignment, deferred). Mutually exclusive with --rhs
  • --rel-tol <REL_TOL> — Relative tolerance for is_close / is_approximately. Overrides the op's default (is_close: 1e-9; is_approximately: 1e-6). Rejected on non-tolerance ops
  • --abs-tol <ABS_TOL> — Absolute tolerance for is_close / is_approximately. Overrides the op's default (is_close: 0.0; is_approximately: 1e-12). Rejected on non-tolerance ops
  • --nan-ok — Treat NaN == NaN as true for tolerance ops (pytest-style). Default false (IEEE-754 NaN != NaN). Rejected on non-tolerance ops
  • --last <LAST> — Lookback duration (e.g. 30s, 5m, 1h). When omitted, live defaults to 30s; trace defaults to the entire file
  • --start <START> — Range start. Accepts ISO 8601 (2025-01-01T00:00:00Z), a date (2025-01-01), a relative offset (-30s / -1.5m / +1h), now, a bare integer (epoch ns), or a bare decimal (epoch seconds). Matches the Python SDK's start= kwarg
  • --end <END> — Range end. Same grammar as --start
  • --temporal <TEMPORAL> — Temporal mode. Defaults to latest when no range is given, always when --last / --start is specified

Possible values: latest, always, ever, never, count

  • --for-duration <FOR_DURATION> — Assert the predicate holds continuously for the given duration (e.g. --for-duration 30s).

  • zelos live check: polls the live store at --interval cadence and terminates fail on the first predicate_false. * zelos trace check: desugars to --temporal=always over the first <duration> of the recording — equivalent to --start <trace.start> --end <trace.start + D> --temporal always.

  • --within-duration <WITHIN_DURATION> — Assert the predicate becomes true at least once within the given duration (e.g. --within-duration 30s).

  • zelos live check: polls until the first satisfied or deadline. * zelos trace check: desugars to --temporal=ever over the first <duration> of the recording.

  • --suite <SUITE> — Run a JSON suite of checks (mutually exclusive with single-check flags)
  • --strict — Require a unique segment per signal path (opt out of newest- segment-wins disambiguation). Default false: when a path resolves to N segments sharing (source, message, signal, producer), the resolver picks the segment with the most recent data. Pass --strict to require a single segment and surface AmbiguousSignal otherwise — useful when a test wants to assert a unique-segment invariant. Cross-producer ambiguity always errors regardless; narrow with --producers
  • --json — Output JSON instead of human-readable
  • -o, --output-artifact <PATH> — Emit a check-result-suite artifact at the given path. Same JSON schema the Python AgentChecker writes, so artifacts from the CLI and from pytest --zelos-local-artifacts-dir=... runs are interchangeable downstream (replay, diff). Atomic tmp-rename write — never leaves a half-file on a crashed run
  • --lookback <LOOKBACK> — Catalog freshness window for signal resolution (e.g. 30s, 5m, 1h). Default 60s, matching agent.latest()

Default value: 60s * --producers <PRODUCERS> — Producer addresses to consult for catalog resolution. Comma- separated list (e.g. localhost,otherhost). Default localhost — same as agent.latest(producers=("localhost",))

Default value: localhost * --interval <INTERVAL> — Polling cadence for --for-duration / --within-duration (e.g. 100ms, 0.2s, 1s). Default 100ms. No effect outside the duration temporals

Default value: 100ms

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

  • --backfill <BACKFILL> — Burst-send historical data before starting live mode. e.g. --backfill 1h sends 1 hour of data at the same frequencies, with timestamps from now-1h to now. Data is sent as fast as possible (no pacing)

zelos trace

Operations on .trz trace files, all routed through the agent.

List signals, query data, run typed predicate checks, and merge multiple traces into a single file. Requires a running agent.

Usage: zelos trace [OPTIONS] <COMMAND>

Subcommands:
  • info — Show trace metadata: file size, time range, segments, per-table row counts
  • signals — List signals in a trace file
  • query — Query signal data from a trace file. Default is M4 downsampled timeseries; pass --raw for unaggregated rows
  • check — Run a typed predicate check against a trace file
  • merge — Merge multiple .trz files into a single trace
  • close — Close cached trace handles on the agent. With no arguments, closes all
Options:
  • --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300

zelos trace info

Show trace metadata: file size, time range, segments, per-table 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 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 the .trz trace file
Options:
  • --json — Output in JSON format

zelos trace query

Query signal data from a trace file. Default is M4 downsampled timeseries; pass --raw for unaggregated rows

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

Examples:

zelos trace query recording.trz -s '*/bus0/BMS_message/status.battery_level' --width 200
zelos trace query recording.trz -s '*/bus0/BMS_message/status.battery_level' --raw -n 50
zelos trace query recording.trz -s '*/eth0/sensor_events.event_type' --raw --format json
Arguments:
  • <FILE> — Path to the .trz trace file
Options:
  • -s, --signals <SIGNALS> — Signal patterns to query (e.g. '*/bus0/BMS_message/status.battery_level')
  • --raw — Return raw rows (TraceQueryAllMulti) instead of M4 downsampled timeseries. Mutually exclusive with --width
  • -w, --width <WIDTH> — Plot width for M4 downsampling (number of output points). Ignored with --raw

Default value: 800 * -n, --limit <LIMIT> — Max rows for --raw (0 = unlimited). Ignored without --raw

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 check

Run a typed predicate check against a trace file

Usage: zelos trace check [OPTIONS] <FILE>

Examples:

zelos trace check recording.trz --lhs-signal '*/bus0/BMS_message/status.cell_voltage' --op gt --rhs 3.0
zelos trace check recording.trz --suite checks.json
Arguments:
  • <FILE> — Path to the .trz trace file
Options:
  • --lhs <LHS> — LHS literal — auto-typed: true/false -> bool, contains . -> float, numeric -> int, else string. Use --lhs=-1.5 for negative numbers. Mutually exclusive with --lhs-signal
  • --lhs-signal <LHS_SIGNAL> — LHS signal path (e.g. bus0/BMS_message/status.cell_voltage or */source/message.signal). Mutually exclusive with --lhs
  • --op <OP> — Comparison operator. Accepts gt|ge|lt|le|eq|ne, the symbolic aliases >, >=, <, <=, ==, != (quote in the shell to dodge redirection), the tolerance / integer ops (is_close, is_approximately, is_divisible_by), and the string / unary ops. Required for non-suite checks

Possible values: gt, ge, lt, le, eq, ne, is_close, is_approximately, is_divisible_by, is_empty, is_positive, is_not_positive, is_negative, is_not_negative, is_true, is_false, contains, starts_with, ends_with, is_in, is_not_in

  • --rhs <RHS> — RHS literal — same auto-typing rules as --lhs. Required for binary ops; rejected for unary ops. Use --rhs=-1.5 for negative numbers
  • --rhs-signal <RHS_SIGNAL> — RHS signal path for signal-vs-signal comparison. Must point at the same {source}/{message} event table as --lhs-signal (cross-table requires alignment, deferred). Mutually exclusive with --rhs
  • --rel-tol <REL_TOL> — Relative tolerance for is_close / is_approximately. Overrides the op's default (is_close: 1e-9; is_approximately: 1e-6). Rejected on non-tolerance ops
  • --abs-tol <ABS_TOL> — Absolute tolerance for is_close / is_approximately. Overrides the op's default (is_close: 0.0; is_approximately: 1e-12). Rejected on non-tolerance ops
  • --nan-ok — Treat NaN == NaN as true for tolerance ops (pytest-style). Default false (IEEE-754 NaN != NaN). Rejected on non-tolerance ops
  • --last <LAST> — Lookback duration (e.g. 30s, 5m, 1h). When omitted, live defaults to 30s; trace defaults to the entire file
  • --start <START> — Range start. Accepts ISO 8601 (2025-01-01T00:00:00Z), a date (2025-01-01), a relative offset (-30s / -1.5m / +1h), now, a bare integer (epoch ns), or a bare decimal (epoch seconds). Matches the Python SDK's start= kwarg
  • --end <END> — Range end. Same grammar as --start
  • --temporal <TEMPORAL> — Temporal mode. Defaults to latest when no range is given, always when --last / --start is specified

Possible values: latest, always, ever, never, count

  • --for-duration <FOR_DURATION> — Assert the predicate holds continuously for the given duration (e.g. --for-duration 30s).

  • zelos live check: polls the live store at --interval cadence and terminates fail on the first predicate_false. * zelos trace check: desugars to --temporal=always over the first <duration> of the recording — equivalent to --start <trace.start> --end <trace.start + D> --temporal always.

  • --within-duration <WITHIN_DURATION> — Assert the predicate becomes true at least once within the given duration (e.g. --within-duration 30s).

  • zelos live check: polls until the first satisfied or deadline. * zelos trace check: desugars to --temporal=ever over the first <duration> of the recording.

  • --suite <SUITE> — Run a JSON suite of checks (mutually exclusive with single-check flags)
  • --strict — Require a unique segment per signal path (opt out of newest- segment-wins disambiguation). Default false: when a path resolves to N segments sharing (source, message, signal, producer), the resolver picks the segment with the most recent data. Pass --strict to require a single segment and surface AmbiguousSignal otherwise — useful when a test wants to assert a unique-segment invariant. Cross-producer ambiguity always errors regardless; narrow with --producers
  • --json — Output JSON instead of human-readable
  • -o, --output-artifact <PATH> — Emit a check-result-suite artifact at the given path. Same JSON schema the Python AgentChecker writes, so artifacts from the CLI and from pytest --zelos-local-artifacts-dir=... runs are interchangeable downstream (replay, diff). Atomic tmp-rename write — never leaves a half-file on a crashed run
  • --producers <PRODUCERS> — Restrict signal resolution to recorders matching this set (comma-separated, e.g. bus0,bus1). Disambiguates multi- producer traces where a bare path like pack.voltage resolves to one signal per recorder. Default empty — accept any recorder; rely on the executor's AmbiguousSignal outcome to flag conflicts

zelos trace merge

Merge multiple .trz files into a single trace

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

zelos trace close

Close cached trace handles on the agent. With no arguments, closes all

Usage: zelos trace close [FILES]...

Examples:

zelos trace close
zelos trace close recording.trz another.trz
Arguments:
  • <FILES> — Specific trace files to evict; omit to close all cached

zelos tools

Debug client for the agent-owned generic tool surface. The agent process is the only thing that defines tool behavior; this CLI just forwards JSON arguments and prints the returned envelope. Local-only by default — pass --allow-network-agent to talk to a remote agent.

Usage: zelos tools [OPTIONS] <COMMAND>

Subcommands:
  • list — List the built-in tools plus existing agent actions
  • call — Call a tool by name
Options:
  • --host <HOST> — Agent host (loopback only unless --allow-network-agent is set)

Default value: localhost:2300 * --allow-network-agent — Permit a non-loopback agent URL. Refused by default

zelos tools list

List the built-in tools plus existing agent actions

Usage: zelos tools list [OPTIONS]

Examples:

zelos tools list
zelos tools list --names-only
Options:
  • --names-only — Print just the tool names, one per line

zelos tools call

Call a tool by name

Usage: zelos tools call [OPTIONS] --tool <TOOL>

Examples:

zelos tools call --tool signals_list --args '{"scope":{"kind":"live"}}'
zelos tools call --tool signals_at_time --args-file query.json
zelos tools call --tool signals_list --raw
Options:
  • --tool <TOOL> — Tool name (e.g. signals_list, action.<service>/<name>)
  • --args <ARGS> — Inline JSON arguments. Defaults to {} when omitted
  • --args-file <ARGS_FILE> — Path to a JSON file containing arguments
  • --context <CONTEXT> — Optional JSON ToolCallContext. Empty means agent defaults
  • --raw — Print the envelope JSON exactly as returned (no pretty-print)

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