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
ZELOS_AGENT_URL Default agent gRPC endpoint for --host (default localhost:2300); an explicit --host wins
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
  • layouts — Manage Zelos layouts
  • live — Interact with live agent data
  • notebook — Create, list, run, export, and convert Zelos notebooks
  • tags — Inspect Zelos tags
  • 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
  • dump — Generate the standalone action inventory for a source directory
  • 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
zelos actions execute "can/convert" --mode standalone
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; 0 means no timeout. Omit to send no budget at all, which leaves the extension to apply the action's own declared timeout; the agent adds no default of its own
  • --mode <MODE> — Where to run the action

Default value: auto

Possible values:

  • auto: Prefer a connected extension, otherwise run from the installed package
  • live: Require a connected extension; fail if there is none
  • standalone: Always run from the installed package, even if the extension is running. Spawns a second process regardless: it does NOT check whether the extension is up, so for an action that touches a device or a file both can contend. Prefer auto unless you specifically need to prove the at-rest path

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 dump

Generate an actions.json inventory for a source directory.

Imports the entry module in that directory's environment and writes what it registered as standalone actions. The agent reads this file — it never generates one — so a development install serves the actions that were in it the last time this ran. zelos extensions package runs the same dump on its own, so a packaged extension always ships a current inventory.

An agent caches what it read, and only an install invalidates that, so a running agent keeps serving the previous inventory: restart it, or reinstall the extension, to pick up a fresh dump.

The environment needs a zelos-sdk providing zelos_sdk.extensions.actions; an extension venv resolves the published SDK from its lockfile, which may predate the harness.

Usage: zelos actions dump [OPTIONS] [PATH]

Examples:

zelos actions dump
zelos actions dump ~/src/zelos-extension-can
zelos actions dump . --entry app.py --out /tmp/actions.json
Arguments:
  • <PATH> — Extension source directory

Default value: .

Options:
  • --entry <ENTRY> — Entry file to import, relative to PATH. Required when the directory has no extension.toml naming an agent-extension runtime entry
  • --out <OUT> — Where to write the inventory [default: /actions.json]

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
  • feedback — Send feedback with a diagnostics bundle, or export the bundle only
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.

With --remote, the --host agent forwards the request to a remote agent it is connected to (the same proxy the desktop app's per-agent Settings dialog uses).

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
zelos agent settings set-bind-address 0.0.0.0
zelos agent settings --remote grpc://robot:2300 set-data-retention 2h
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", "disk", or "metadata"). 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)
  • set-bind-address — Set the desktop app-agent bind address. Requires agent restart
  • clear-store — Clear all data from the store (irreversible)
Options:
  • --json — Output in JSON format (for viewing)
  • --remote <REMOTE> — Forward to a remote agent CONNECTED to the --host agent, addressed exactly as it was connected (e.g. "grpc://robot:2300"). Errors if the --host agent has no live connection to that address

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", "disk", or "metadata"). Requires agent restart

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

Arguments:
  • <VALUE> — "memory" (ArrowStore), "disk" (Parquet), or "metadata" (catalog only, no data — headless agents only)

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 set-bind-address

Set the desktop app-agent bind address. Requires agent restart

Usage: zelos agent settings set-bind-address <VALUE>

Arguments:
  • <VALUE> — IP literal ("0.0.0.0" for all interfaces, "192.168.1.10", "[::1]"), or "none" for the default localhost-only

zelos agent settings clear-store

Clear all data from the store (irreversible)

Usage: zelos agent settings clear-store

zelos agent feedback

Send feedback to Zelos support with a diagnostics bundle (the last 24 hours of logs, settings, and system info — capped and scrubbed), or build the bundle locally with --export-only and share it yourself.

Usage: zelos agent feedback [OPTIONS]

Examples:

zelos agent feedback -m "plots stopped updating after reconnect"
zelos agent feedback -m "plots stopped updating" --email [email protected]
zelos agent feedback --export-only
zelos agent feedback -m "cli smoke" --json
Options:
  • -m, --message <MESSAGE> — Description of the problem (required unless --export-only)
  • --email <EMAIL> — Contact email for follow-up
  • --export-only — Build the diagnostics bundle without sending anything
  • --json — Output in JSON format

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
zelos extensions package ./my-extension --skip-actions-dump
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
  • --skip-actions-dump — Skip generating actions.json (the standalone-action inventory)

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 layouts

Manage Zelos layouts.

List, show, create, update, and delete saved dashboard layouts. Layouts are stored in Zelos Cloud and require console login (run zelos login).

Without --organization the agent uses its active organization (resolved at connection, see zelos login); pass --organization to work in another organization.

Usage: zelos layouts [OPTIONS] <COMMAND>

Subcommands:
  • list — List all layouts
  • show — Show a single layout, including its layout data JSON
  • versions — List a layout's version history
  • restore — Restore a layout to a previous version
  • label — Name a version in a layout's history
  • create — Create a new layout
  • update — Update an existing layout
  • delete — Delete a layout
Options:
  • --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300 * --organization <ORGANIZATION> — Organization slug (default: the agent's active organization)

zelos layouts list

List all layouts

Usage: zelos layouts list [OPTIONS]

Examples:

zelos layouts list
zelos layouts list --organization acme
zelos layouts list --json
Options:
  • --json — Output in JSON format

zelos layouts show

Show a single layout, including its layout data JSON

Usage: zelos layouts show [OPTIONS] <ID>

Examples:

zelos layouts show 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01
zelos layouts show 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 --version 3
zelos layouts show 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 --json
Arguments:
  • <ID> — Layout ID (UUID)
Options:
  • --version <VERSION> — Show a specific version from the layout's history (default: current)
  • --json — Output in JSON format

zelos layouts versions

List a layout's version history, newest first. A new version is recorded on every content-changing save; restores append a new version rather than rewriting history. Use zelos layouts show <id> --version <n> to inspect a version's data and zelos layouts restore to roll back.

Usage: zelos layouts versions [OPTIONS] <ID>

Examples:

zelos layouts versions 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01
zelos layouts versions 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 --json
Arguments:
  • <ID> — Layout ID (UUID)
Options:
  • --json — Output in JSON format

zelos layouts restore

Restore a layout to a previous version. The restored state is appended to the history as a new version, so nothing is lost — the pre-restore state remains restorable.

Usage: zelos layouts restore [OPTIONS] <ID> <VERSION>

Examples:

zelos layouts restore 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 3
Arguments:
  • <ID> — Layout ID (UUID)
  • <VERSION> — Version number to restore (see zelos layouts versions)
Options:
  • --json — Output in JSON format

zelos layouts label

Set or clear a version's name. Named versions are easier to find and are kept forever (they are exempt from history retention). A layout can have at most 40 named versions.

Usage: zelos layouts label [OPTIONS] <ID> <VERSION> [LABEL]

Examples:

zelos layouts label 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 3 "Golden config"
zelos layouts label 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 3 --clear
Arguments:
  • <ID> — Layout ID (UUID)
  • <VERSION> — Version number (see zelos layouts versions)
  • <LABEL> — The version name to set
Options:
  • --clear — Clear the version's name
  • --json — Output in JSON format

zelos layouts create

Create a new layout. Provide the layout data as an inline JSON string (--data) or from a file (--data-file). By default the layout is a team layout; pass --personal to make it personal.

Usage: zelos layouts create [OPTIONS] <NAME>

Examples:

zelos layouts create "My Dashboard" --data '{"panels": []}'
zelos layouts create "My Dashboard" --data-file layout.json
zelos layouts create "My Dashboard" --data '{"panels": []}' --personal
Arguments:
  • <NAME> — Layout name
Options:
  • --data <DATA> — Layout data as an inline JSON string
  • --data-file <DATA_FILE> — Path to a file containing the layout data JSON
  • --personal — Create a personal layout (default: team layout)
  • --json — Output in JSON format

zelos layouts update

Update an existing layout. At least one of --name, --data/--data-file, or --personal must be provided. Unspecified fields keep their current values (the current layout is fetched first and merged).

Usage: zelos layouts update [OPTIONS] <ID>

Examples:

zelos layouts update 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 --name "Renamed"
zelos layouts update 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 --data-file layout.json
zelos layouts update 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01 --personal false
Arguments:
  • <ID> — Layout ID (UUID)
Options:
  • --name <NAME> — New layout name
  • --data <DATA> — New layout data as an inline JSON string
  • --data-file <DATA_FILE> — Path to a file containing the new layout data JSON
  • --personal <PERSONAL> — Set whether the layout is personal (true or false)

Possible values: true, false

  • --json — Output in JSON format

zelos layouts delete

Delete a layout

Usage: zelos layouts delete <ID>

Examples:

zelos layouts delete 018f8e2a-1b2c-7d3e-9f4a-5b6c7d8e9f01
Arguments:
  • <ID> — Layout ID (UUID)

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
  • events — List event entries (per-table, not per-column) from connected agents
  • checks — Convenience alias for zelos live events --event-type 'zelos.check.*'
  • annotations — Convenience alias for zelos live events --event-type 'zelos.annotation.*'
  • 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
  • annotate — Inject a zelos.annotation.comment.v1 event into the agent's live store
  • demo — Publish mock device data to the agent for testing
  • backfill — Backfill data from a connected remote agent
  • connect — Connect to a remote agent
  • disconnect — Disconnect from a remote agent
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
  • --per-segment — One entry per (agent, path, data segment) instead of one per (agent, path) — the catalog shape the desktop app's segment-overlap detection consumes
  • --lookback <LOOKBACK> — Catalog freshness window for live signal or event-table discovery (e.g. 30s, 5m, 1h). Default 60s

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 events

List event entries (per-table, not per-column) from connected agents

Usage: zelos live events [OPTIONS]

Examples:

zelos live events                                # every event table (default)
zelos live events --event-type 'zelos.check.*'   # trailing-* prefix glob
zelos live events --event-type 'zelos.log.v1'    # exact event type
zelos live events --latest                       # + each table's newest row timestamp
zelos live events --latest --json

events lists what was DECLARED; events --latest shows whether rows are actually arriving. A table that registered a schema but has emitted nothing appears in both — with no rows under --latest.

Options:
  • --event-type <EVENT_TYPES> — Event type to list: exact match (zelos.check.result.v1) or a trailing-* prefix glob (zelos.check.*). * lists every table. Repeat to OR multiple filters. Default: *
  • --latest — Show each table's most recent row instead of just listing the table.

The catalog is populated by the event's schema alone, so a listing proves only that a table was DECLARED. --latest is the "is data actually flowing?" probe — the events analog of live latest. * --json — Output in JSON format * --lookback <LOOKBACK> — Catalog freshness window for live signal or event-table discovery (e.g. 30s, 5m, 1h). Default 60s

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 checks

Convenience alias for zelos live events --event-type 'zelos.check.*'

Usage: zelos live checks [OPTIONS]

Options:
  • --latest — Show each table's most recent row instead of just listing the table.

The catalog is populated by the event's schema alone, so a listing proves only that a table was DECLARED. --latest is the "is data actually flowing?" probe — the events analog of live latest. * --json — Output in JSON format * --lookback <LOOKBACK> — Catalog freshness window for live signal or event-table discovery (e.g. 30s, 5m, 1h). Default 60s

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 annotations

Convenience alias for zelos live events --event-type 'zelos.annotation.*'

Usage: zelos live annotations [OPTIONS]

Options:
  • --latest — Show each table's most recent row instead of just listing the table.

The catalog is populated by the event's schema alone, so a listing proves only that a table was DECLARED. --latest is the "is data actually flowing?" probe — the events analog of live latest. * --json — Output in JSON format * --lookback <LOOKBACK> — Catalog freshness window for live signal or event-table discovery (e.g. 30s, 5m, 1h). Default 60s

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 --last 5m -o capture.trz --format trz2 --name 'dyno run 14'
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). --format trz2 seals ONE producer, so it takes at most one address
  • --format <FORMAT> — Output format. Legacy DuckDB is the release default; TRZ2 is the sealed catalog+Parquet tar

Default value: legacy

Possible values:

  • legacy: Legacy DuckDB .trz (the release default)

  • trz2: TRZ2 — sealed catalog + Parquet in an uncompressed tar

  • --name <NAME> — Human-readable trace name, stamped into the sealed catalog at seal time. TRZ2 only (--format trz2); the legacy format has no catalog to carry it. Write-only for now: the name rides in the trace metadata but is not yet surfaced by trace info or the app

  • -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 '*/logger/log.message' --last 30s
zelos live query-ts -s '*/logger/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]

Side effect: the agent records each result as a zelos.check.result.v1 event (source checks) in its live store — queryable via zelos live checks, visible on the timeline, and included in exports. Pass --no-emit to evaluate only. Pure-literal checks (no signal operand) and --for-duration / --within-duration polls are never recorded.

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 --no-emit
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 live signal or event-table discovery (e.g. 30s, 5m, 1h). Default 60s

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 * --no-emit — Don't record results. By default the agent writes one zelos.check.result.v1 event per result into its live store (source checks), so runs are queryable via zelos live checks and show on the timeline. --no-emit evaluates only

zelos live annotate

Inject an annotation comment into the agent's live store.

Annotations are stored as zelos.annotation.comment.v1 trace events alongside signal data; they survive trace exports and appear on the timeline. Useful for marking interesting moments programmatically (CI failures, manual checkpoints, post-run notes).

Usage: zelos live annotate [OPTIONS] --name <NAME>

Examples:

zelos live annotate --name 'voltage anomaly' --status warn --author [email protected] \
  --text 'noticed a 0.5V dip here' --target-path 'bus0/BMS.cell_voltage'

zelos live annotate --name 'release candidate' --tags 'qa,review' --time-ns 1735689600000000000

zelos live annotate --name 'fault window' --range-start-ns 1700000000000000000 \
  --range-end-ns 1700000030000000000 --status error
Options:
  • --name <NAME> — Short label (required)
  • --status <STATUS> — Status color hint: info | ok | warn | error (default neutral)
  • --author <AUTHOR> — Author identity (email/handle). Defaults to $USER if unset
  • --text <TEXT> — Comment body
  • --target-path <TARGET_PATH> — Signal/panel path the annotation refers to
  • --range-start-ns <RANGE_START_NS> — Start of the annotation range (epoch nanoseconds)
  • --range-end-ns <RANGE_END_NS> — End of the annotation range (epoch nanoseconds)
  • --tags <TAGS> — Optional comma-separated tags
  • --time-ns <TIME_NS> — Explicit point-in-time (epoch ns). Defaults to wall-clock now() server-side

zelos live demo

Publish mock device data to the agent for testing.

Simulates BMS, DCDC, inverter, and sensor devices at various frequencies, a zelos.log.v1 text-log stream on the logger source, and typed events/spans/check results on the demo source. Press Ctrl+C to stop (or use --duration).

Usage: zelos live demo [OPTIONS]

Examples:

zelos live demo
zelos live demo -d bms --duration 30s
zelos live demo -d log --duration 30s
zelos live demo -d events --duration 30s
Options:
  • -d, --device <DEVICE> — Mock device types to simulate

Default value: all

Possible values:

  • all: All mock devices (BMS + DCDC + Inverter + Sensor + Log + Events)
  • 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)
  • log: Text log stream, zelos.log.v1 (5 Hz)

  • events: Typed events + spans + checks — zelos.{event,span,check.result}.v1 (1 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)
  • --scope — Use the oscilloscope source instead of the ECU mock devices. Emits a single scope source with one samples event carrying four sine-wave channels (1Hz, 10Hz, 100Hz, 1kHz) sampled at --sample-rate (default 10 kHz). Generates dense data — useful for stressing the backfill path with large transfers
  • --sample-rate <SAMPLE_RATE> — Sample rate (Hz) for --scope. Ignored when --scope is not set

Default value: 10000

zelos live backfill

Request historical data from a connected remote agent.

Opens a fresh bounded Subscribe RPC for [now-duration, now], clears the local mirror store first to avoid duplicate accumulation, then forwards the delivered window into it. The RPC closes when the remote agent has streamed the requested window.

Usage: zelos live backfill [OPTIONS] <ADDRESS>

Examples:

zelos live backfill 192.168.1.50:2300 --last 30s
zelos live backfill my-edge-agent:2300 --last 5m
Arguments:
  • <ADDRESS> — Remote agent address (must already be connected)
Options:
  • -l, --last <LAST> — How far back to request data

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

zelos live connect

Connect to a remote agent

Usage: zelos live connect <ADDRESS>

Arguments:
  • <ADDRESS> — Remote agent address (e.g. 192.168.1.50:2300)

zelos live disconnect

Disconnect from a remote agent

Usage: zelos live disconnect <ADDRESS>

Arguments:
  • <ADDRESS> — Remote agent address

zelos notebook

Create, list, run, export, and convert Zelos notebooks.

A Zelos notebook is plain markdown with optional YAML front matter (description, authors, dependencies, params, tool.uv) and top-level ```python fenced cells. A notebook's name is its file name. Runs execute against the agent's managed uv environment and kernel.

Usage: zelos notebook [OPTIONS] <COMMAND>

Subcommands:
  • new — Write a starter notebook in your notebooks folder (never overwrites)
  • list — List the notebooks in your notebooks folder with what their front matter says
  • run — Run cells and stream their output live
  • publish — Publish the notebook's saved state to Zelos Cloud, without running it
  • pull — Save a cloud notebook into your notebooks folder as a new file
  • rename — Rename or move a notebook or folder (never overwrites)
  • copy — Copy a notebook (never overwrites; stored outputs do not follow)
  • delete — Permanently delete a notebook or folder and its stored outputs
  • mkdir — Create a folder in your notebooks folder
  • import — Convert a Jupyter notebook to the Zelos format
  • env — Environment (uv) provisioning
Options:
  • --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300

zelos notebook new

Write a starter notebook and print where it landed.

A name goes in your notebooks folder, subfolders included (tests/gate.md). To write somewhere else, say where with a path starting ./, ../, or /.

A notebook is markdown, so a name without a .md or .markdown extension gets .md.

A taken name is never overwritten: the notebook lands on the nearest free "name N" sibling, and the printed path says where.

Usage: zelos notebook new <PATH>

Examples:

zelos notebook new analysis.md
zelos notebook new analysis            # the same file
zelos notebook new tests/release-gate.md
zelos notebook new ./analyses/thermal.md
Arguments:
  • <PATH> — Name of the notebook (e.g. analysis.md), or a ./ path to write elsewhere

zelos notebook list

List notebooks and what they say about themselves.

With no path, searches your notebooks folder — the one the agent creates for you. Pass a path to search somewhere else, . for the current directory.

Searches recursively, skipping dot entries, for markdown files. Each row is headed by the notebook's name, read off its file name, followed by its description and authors. A file whose front matter does not parse is listed with the error rather than skipped.

Usage: zelos notebook list [OPTIONS] [PATH]

Examples:

zelos notebook list
zelos notebook list ./analyses --json
Arguments:
  • <PATH> — Directory to search, or a single notebook file (default: your notebooks folder)
Options:
  • --json — Output in JSON format

zelos notebook run

Run a notebook's cells against the agent and stream output live.

With no --cell, every code cell runs in document order. Stream text prints verbatim; rich outputs are summarized as one-liners; tracebacks print in full. Ctrl-C interrupts the run.

Pass -o <file> to also write a rendered page — a self-contained HTML document (.html) or a Jupyter notebook (.ipynb), chosen by the file extension. Run provenance rides inside the artifact.

Exit status: 0 succeeded, 1 failed or errored, 2 an infrastructure failure (connection, session, or stream), 130 interrupted.

Usage: zelos notebook run [OPTIONS] <PATH>

Examples:

zelos notebook run analysis.md
zelos notebook run analysis.md -o analysis.html
zelos notebook run analysis.md -o analysis.ipynb --param window=30
zelos notebook run analysis.md --cell 0 --cell 2
Arguments:
  • <PATH> — Notebook name or path; a bare name resolves here, then in your notebooks folder
Options:
  • --cell <N> — Code-cell index to run (repeatable); omit to run all cells
  • --param <KEY=VALUE> — Parameter override as key=value (repeatable). A declared param coerces the value toward its default's type (a number default makes 30 an integer, a bool default reads true/false, a list or map default parses the value as YAML); a string default keeps it a string. Front-matter params are defaults, not a schema, so an undeclared key defines a new param and its value is parsed as YAML on its own
  • -o, --output <FILE> — Also write the rendered page for the run to this file; the format is inferred from the extension (.html or .ipynb). The run still streams to the terminal. Run provenance rides inside the artifact
  • --offline — Provision from the local uv cache only; fails rather than using the network
  • --dry-run — Provision and verify the environment, print the run plan, then exit without executing any cell
  • --publish — After the run settles, publish to Zelos Cloud (errored runs publish too — a failed test is exactly the run someone needs to see)
  • --org <ORG> — Zelos Cloud organization slug; needed only when you belong to several
  • --visibility <VISIBILITY> — With --publish, who can see the cloud notebook (first publish only)

Default value: org

Possible values: org, personal

  • --tag <NAME> — With --publish, an existing organization tag to add (repeatable); never removes a tag the notebook already carries

zelos notebook publish

Publish the notebook to Zelos Cloud as an immutable VERSION: the source snapshot and the stored outputs of its last run. Publishing always ADDS a version — it never replaces anyone's work.

The first publish writes a tenant-qualified cloud remote into the front matter, so this file — and every git clone of it — publishes to the same cloud notebook from then on.

Publishes count against your organization's Zelos Cloud storage. Sign in with zelos login or from the Zelos app.

--tag ADDS existing organization tags to the cloud notebook and may be repeated. Names match case-insensitively and must already exist in the organization's vocabulary (see zelos tags list); an unknown one fails before anything is published, rather than creating a tag.

Adding only: a publish never removes a tag, so a scheduled run cannot wipe labels somebody curated. A notebook's tags describe what it is about and outlive any one version. Remove them in the app's notebook header or the console's notebook list.

Exit status: 0 published, 2 an infrastructure failure.

Usage: zelos notebook publish [OPTIONS] <PATH>

Examples:

zelos notebook publish analysis.md
zelos notebook publish analysis.md --org acme --visibility personal
zelos notebook publish analysis.md --tag battery --tag ci
zelos notebook publish analysis.md --new   # fork to a fresh cloud notebook
Arguments:
  • <PATH> — Notebook name or path; a bare name resolves here, then in your notebooks folder
Options:
  • --org <ORG> — Zelos Cloud organization slug; needed only when you belong to several
  • --visibility <VISIBILITY> — Who can see the cloud notebook (first publish only)

Default value: org

Possible values: org, personal

  • --tag <NAME> — Existing organization tag to add (repeatable, case-insensitive); never removes one already carried
  • --new — Ignore an existing remote and fork to a fresh cloud notebook
  • --json — Output the publish coordinates as JSON

zelos notebook pull

Save a published notebook from Zelos Cloud into your notebooks folder: its source, its outputs, and its environment lock. Always a new file, never an overwrite. The newest version unless --version names one.

Usage: zelos notebook pull [OPTIONS] <NOTEBOOK_ID>

Examples:

zelos notebook pull 7b7f3d24-9c1a-4f6e-8a2d-5e0c1b9f4a33
zelos notebook pull 7b7f3d24-9c1a-4f6e-8a2d-5e0c1b9f4a33 --org acme --version 3f0e…
Arguments:
  • <NOTEBOOK_ID> — The cloud notebook id (the UUID in its console URL)
Options:
  • --org <ORG> — Zelos Cloud organization slug; needed only when you belong to several
  • --version <PUBLISH_ID> — A specific publish id to save instead of the newest
  • --json — Output in JSON format

zelos notebook rename

Rename or move a notebook or a folder.

Both ends must be inside your notebooks folder: the agent opens and runs notebooks from anywhere, but only moves files within the folder it owns.

Stored outputs and the provisioned environment follow the file. The destination must not exist, and a notebook the agent holds open must be closed first. A notebook source keeps its own markdown extension unless the destination states one.

Usage: zelos notebook rename <FROM> <TO>

Examples:

zelos notebook rename analysis.md triage.md
zelos notebook rename analysis.md archive/analysis.md   # move
zelos notebook rename drafts archive/drafts             # a folder
Arguments:
  • <FROM> — Notebook or folder to rename; a bare name resolves in your notebooks folder
  • <TO> — New name or destination path

zelos notebook copy

Copy a notebook under a new name.

The agent slugs the name into a file name, and the copy lands beside the source, keeping the source's own markdown extension. Never overwrites, and stored outputs do not follow: a copy is a new notebook that has not run.

Usage: zelos notebook copy <PATH> <NAME>

Examples:

zelos notebook copy analysis.md "analysis v2"
Arguments:
  • <PATH> — Notebook to copy; a bare name resolves in your notebooks folder
  • <NAME> — What the copy is called, as you would write it

zelos notebook delete

Permanently delete a notebook or a folder, together with the stored outputs and provisioned environment of everything under it. There is no trash; requires --force.

Only paths inside your notebooks folder can be deleted. The agent opens and runs notebooks from anywhere on disk, but it will not remove files outside the folder it owns — delete those yourself.

Usage: zelos notebook delete [OPTIONS] <PATH>

Examples:

zelos notebook delete analysis.md --force
Arguments:
  • <PATH> — Notebook or folder to delete; a bare name resolves in your notebooks folder
Options:
  • --force — Actually delete; without this the command refuses and explains

zelos notebook mkdir

Create a folder in your notebooks folder

Usage: zelos notebook mkdir <PATH>

Examples:

zelos notebook mkdir archive
Arguments:
  • <PATH> — Folder name or path

zelos notebook import

Convert a Jupyter .ipynb to a Zelos notebook markdown file.

Code cells become ``python fences keeping theircell.idwhen it is already a valid Zelos id, markdown cells become prose, outputs are dropped, and kernelspec is ignored.metadata.authorsand themetadata.zelos` block a Zelos export writes come back as front matter, so an exported notebook round-trips.

Usage: zelos notebook import --out <OUT> <SRC>

Examples:

zelos notebook import notebook.ipynb --out analysis.md
Arguments:
  • <SRC> — Source Jupyter notebook (.ipynb)
Options:
  • -o, --out <OUT> — Destination Zelos notebook markdown file

zelos notebook env

Environment (uv) provisioning

Usage: zelos notebook env <COMMAND>

Subcommands:
  • warm — Provision the notebook's environment and wait until it is ready

zelos notebook env warm

Provision the notebook's environment and wait until it is ready

Usage: zelos notebook env warm [OPTIONS] <PATH>

Examples:

zelos notebook env warm analysis.md
Arguments:
  • <PATH> — Notebook name or path; a bare name resolves here, then in your notebooks folder
Options:
  • --offline — Provision from the local uv cache only; fails rather than using the network

zelos tags

Inspect the organization's tag vocabulary.

Tags are org-scoped labels applied to cloud traces, layouts, and notebooks (the CLI applies them with zelos trace upload --tag and zelos notebook publish --tag). They are curated in the console and the desktop app — the CLI reads them but never creates one, since a name in a script is a typo nobody sees. Stored in Zelos Cloud; requires console login (run zelos login).

Usage: zelos tags [OPTIONS] <COMMAND>

Subcommands:
  • list — List the organization's tags
Options:
  • --host <HOST> — Agent gRPC endpoint

Default value: localhost:2300

zelos tags list

List the organization's tags, oldest first, with how many items carry each one (traces, shared layouts, and org notebooks).

Without --organization the agent uses its active organization (resolved at connection, see zelos login); pass --organization to read another organization's vocabulary.

Usage: zelos tags list [OPTIONS]

Examples:

zelos tags list
zelos tags list --organization acme
zelos tags list --json
Options:
  • --organization <ORGANIZATION> — Organization slug (default: the agent's active organization)
  • --json — Output in JSON format

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
  • events — List event entries (per-event-table) in one or more trace files
  • 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
  • export — Export traces to a new file (optionally windowed; legacy or TRZ2 format)
  • merge — Merge multiple .trz files into a single trace
  • close — Close cached trace handles on the agent. With no arguments, closes all
  • upload — Upload a trace to the cloud (the live session, or a sealed .trz directory)
  • download — Download a cloud trace to a local .trz file
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
zelos trace info recording.trz --files
Arguments:
  • <FILE> — Path to the .trz trace file
Options:
  • --json — Output in JSON format
  • --files — Also list each event table's Parquet files: the directory (segment/table uuids) the files live in, and their count and size

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 events

List event entries (per-event-table) in one or more trace files

Usage: zelos trace events [OPTIONS] <FILES>...

Examples:

zelos trace events recording.trz                                      # every event table (default)
zelos trace events recording.trz --event-type 'zelos.check.*'         # trailing-* prefix glob
zelos trace events recording.trz --event-type 'zelos.annotation.*' --json
Arguments:
  • <FILES> — Paths to .trz trace files (at least one required)
Options:
  • --event-type <EVENT_TYPES> — Event type to list: exact match (zelos.check.result.v1) or a trailing-* prefix glob (zelos.check.*). * lists every table. Repeat to OR multiple filters. Default: *
  • --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 export

Export traces to a new file (optionally windowed; legacy or TRZ2 format)

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

Examples:

zelos trace export capture.trz -o out.trz
zelos trace export capture.trz -o out.trz --format trz2
zelos trace export a.trz b.trz -o merged.trz --start 2026-01-01T00:00:00Z --end 2026-01-01T01:00:00Z
Arguments:
  • <INPUTS> — Input trace files (legacy .trz; TRZ2 inputs require --format trz2)
Options:
  • -o, --output <OUTPUT> — Output file path
  • --start <START> — Window start (with --end). Accepts the CLI's shared time grammar: now, a date (2025-01-01), a relative offset (-30s / -1.5m / +1h), ISO 8601 / RFC 3339, or epoch ns/seconds
  • --end <END> — Window end (with --start). Same grammar as --start
  • --format <FORMAT> — Output format. Legacy DuckDB is the release default; TRZ2 is the sealed catalog+Parquet tar

Default value: legacy

Possible values:

  • legacy: Legacy DuckDB .trz (the release default)

  • trz2: TRZ2 — sealed catalog + Parquet in an uncompressed tar

  • --name <NAME> — Human-readable trace name, stamped into the sealed catalog at seal time. TRZ2 only (--format trz2); the legacy format has no catalog to carry it. Write-only for now: the name rides in the trace metadata but is not yet surfaced by trace info or the app

  • -f, --force — Overwrite output if it exists

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 trace upload

Upload a trace to Zelos Cloud — either the agent's live session (--live) or a sealed trz2 directory.

Without --organization the trace goes to your ACTIVE organization (the one the console last put you in); the upload reports which one it used. Pass --organization to upload elsewhere — a slug you are not a member of fails before anything is created.

Without --name the trace is labeled trace_<timestamp>, the same convention zelos live export names its output file with.

Uploads count against your organization's Zelos Cloud storage.

--tag applies existing organization tags to the upload and may be repeated. Names match case-insensitively and must already exist in the organization's vocabulary (see zelos tags list); an unrecognized name fails before the upload starts rather than creating a tag.

Usage: zelos trace upload [OPTIONS] [PATH]

Examples:

zelos trace upload --live
zelos trace upload --live --organization acme
zelos trace upload ./sealed-trace/ --organization acme --name nightly-run
zelos trace upload --live --tag bms --tag thermal
Arguments:
  • <PATH> — A sealed trz2 directory to upload (mutually exclusive with --live)
Options:
  • --organization <ORGANIZATION> — Organization slug to upload under (defaults to your active organization)
  • --live — Upload the agent's live session (mutually exclusive with PATH)
  • --name <NAME> — Human-facing label for the uploaded trace (default: trace_)
  • --tag <NAME> — Existing organization tag to apply (repeatable, case-insensitive)

zelos trace download

Download a cloud trace to a local TRZ2 (.trz) file.

A cloud trace is STORED as TRZ2 content, so this is a repack, not a conversion: the same bytes come down and are packed into one file, which is then verified before the download reports success.

Usage: zelos trace download [OPTIONS] <REF>

Examples:

zelos trace download 'zelos://open?org=acme&trace=0198f0e1-...'
zelos trace download 'zelos://open?org=acme&trace=0198f0e1-...' -o dyno.trz --force
Arguments:
  • <REF> — Cloud trace ref: zelos://open?org=&trace=
Options:
  • -o, --output <OUTPUT> — Output file path (default: .trz in the current directory)
  • -f, --force — Overwrite output if it exists

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. Built-ins use stable names such as signal_list; action-backed tools appear in tools list as ext_<slug> names. 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 signal_list --args '{"scope":{"kind":"live"}}'
zelos tools call --tool event_list --args '{"scope":{"kind":"live","agents":["localhost"],"durationSeconds":60},"eventTypes":["zelos.check.*"]}'
zelos tools call --tool event_list --args '{"scope":{"kind":"trace","tracePaths":["/tmp/run.trz"]}}'
zelos tools call --tool signal_at_time --args-file query.json
zelos tools call --tool signal_list --raw

event_list applies durationSeconds only to live discovery (default 60 seconds). Trace scope lists the whole bounded trace and has no lookback window.

Options:
  • --tool <TOOL> — Tool name (e.g. signal_list, ext_zeloscloud_can_transmit)
  • --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