litmus-cli - Command-Line Interface for Litmus

You are reading this at https://api.litmus.io/cli.md (HTML version at https://api.litmus.io/cli).

litmus-cli is the standalone command-line client for Litmus Edge, Litmus Edge Manager, and Litmus Unify. It exposes the full Litmus SDK surface (~1250 functions) as shell commands with JSON output, and is the preferred method for AI agents and agentic tasks: no code to write, install, or run.

Ecosystem Context

What it is

litmus-cli is the standalone command-line client for the Litmus APIs: the full SDK surface (~1250 functions) as shell commands with JSON output, covering Litmus Edge, Litmus Edge Manager, and Litmus Unify. It is the preferred method for AI agents and agentic tasks.

• A single statically linked binary, no runtime dependencies, built from the Litmus Go SDK (whose public source release is in the works).
• Released under cli-v* tags at https://github.com/litmusautomation/litmus-sdk-releases/releases (latest: cli-v1.0.0). Prebuilt for macOS arm64, Linux amd64/arm64, and Windows amd64.
• Results are JSON on stdout, errors on stderr, so output pipes cleanly into jq, scripts, and agent tool calls.
• Covers Litmus Edge (including the DataHub data plane), Litmus Edge Manager, and Litmus Unify, including all mutations.
• Supported versions (cli-v1.0.0+): Litmus Edge 4.4.x and Litmus Edge Manager 3.0.x (LTS), Litmus Unify 2.0.x. Litmus Edge 4.0.x and Edge Manager 2.31.x work best-effort: functions new in Litmus Edge 4.4 fail on 4.0 with a clear "requires Litmus Edge 4.4 or later" error, and functions new in Edge Manager 3.0 fail on 2.31 with the server's 404 (unexpected status 404 (expected 200)). Litmus Edge 3.x and Edge Manager releases older than 2.31 are no longer supported.
• Stable from cli-v1.0.0: run paths and --args names do not change within 1.x, so scripts and agent prompts written against one 1.x release keep working.
• Not part of the litmussdk Python package. Until June 2026 a Python console script named litmus-sdk-cli shipped with the wheel; see the migration table in https://api.litmus.io/sdk-agents.md if you are moving from it.

What's new in cli-v1.0.0

First stable release. Litmus Edge 4.4.x and Litmus Edge Manager 3.0.x are the supported LTS releases, and the CLI follows semantic versioning from here on.

• ~1250 functions, up from ~1000. 104 new Litmus Edge 4.4 operations (saved templates and snapshots, system log query and log forwarding, analytics workspaces, groups, component variables and AI Suite, OPC UA paged navigation and worker sync, DeviceHub search tasks, Digital Twins asset hierarchy) and 134 new Edge Manager 3.0 operations (asset hierarchy, Asset Hub, device HA, device OAuth clients, edge logs, platform rules, CA certificates, audit records v2, instance async tasks), in lem.* and lem.admin.*.
• Version-aware. Calls pick the right request shape from the device firmware, and functions new in a release are marked LE 4.4+ or LEM 3.0+ in their --help.
• Security. Built with Go 1.26.9, which clears the Go standard library CVEs in cli-v0.13.0. Run litmus-cli update.

Breaking and behavior changes - check scripts that call:

• lem.CreateTemplate, lem.admin.UploadEdgeDeviceTemplate, lem.admin.UpdateEdgeDeviceTemplateDescription: now take friendlyName, which Edge Manager 3.0 requires.
• le.integrations provider IDs: these are the Litmus Edge 4.4 UUIDs. le.integrations.ResolveProviderID and LookupProvider map them to the 4.0 slugs on 4.0 devices.
• le.analytics.GetAnalyticsParameters and SetAnalyticsParameter: deprecated, and they fail on Litmus Edge 4.4, which removed global parameters. ExportGroup returns ComponentVariables instead of Parameters on 4.4.
• le.devicehub.CreateBrowseTask: always sends DeviceBrowseParams and TaskParams, which Litmus Edge 4.4 requires.
• Deprecated: Edge Manager Sites (removed in 3.0), and lem.admin.ListAuditLogs / ListAuditLogContexts (use ListAuditRecords / ListAuditCategories).

Known issues in cli-v1.0.0:

• lem.admin.PullRegistryImage still sends the 2.31 query-string form; Edge Manager 3.0 expects a JSON body.
• lem.EnableDisableForwarding still uses GET; Edge Manager 3.0 documents POST.

Install and update

# macOS / Linux: detects platform, verifies SHA256, installs to ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/litmusautomation/litmus-sdk-releases/main/install.sh | sh

# Windows: download litmus-cli-windows-amd64.exe from the latest cli-v* release at
# https://github.com/litmusautomation/litmus-sdk-releases/releases and put it on PATH.

litmus-cli version   # print CLI version and build details
litmus-cli update    # self-update in place to the latest cli-v* release

Command overview

Every command and SDK package has built-in docs via --help.

Discover and run any SDK function

The list / run pair is the core workflow, and the reason the CLI works so well for AI agents: discover the exact function path and arguments, then call it.

# Discover - lists every callable path with argument names
litmus-cli list                 # top-level packages
litmus-cli list le.devicehub    # functions in one package
litmus-cli list lem.Get         # filter by any dotted-path prefix

# Read the docs before calling
litmus-cli list le.devicehub --help                # full docs for that SDK package
litmus-cli run le.devicehub.ListDeviceTags --help  # signature + ready-to-fill --args skeleton

# Run - result is JSON on stdout, errors on stderr
litmus-cli run le.devicehub.ListDevices
litmus-cli run lem.ListIncidents --args '{"projectID": "my-project"}'
litmus-cli run unify.GetNamespace

Litmus Edge packages live under the le. prefix: le.devicehub, le.system, le.analytics, le.digitaltwins, le.flows, le.integrations, le.marketplace, le.opc. Edge Manager and Unify paths are lem.* and unify.* with no extra prefix; the LEM Admin Console (installation-wide settings) is lem.admin.* (cli-v0.13.0+). Live streams and subscriptions (events, device status, processor output) take maxEvents/seconds style bounds and return what arrived (cli-v0.13.0+). Argument keys are camelCase; list <pkg> shows the exact names.

Recommended agent loop: list <prefix> to find the function, run <path> --help for the argument skeleton, then run <path> --args '{...}'.

Curated shortcuts

Common reads are one short command, no dotted path needed.

Litmus Edge (litmus-cli le ...)

Litmus Edge Manager (litmus-cli lem ...)

Anything not covered by a shortcut is reachable through run - the shortcuts and the dotted paths hit the same SDK underneath.

Data plane: live and historical tag data

litmus-cli le data reaches past the REST API to the device data plane: live tag values and tag writes through the DataHub broker (NATS, port 4222), and historical values from the device time-series database (InfluxDB, port 8086, database tsdata). Both authenticate separately from the REST API; litmus-cli le data --help explains the credentials.

On a device you administer, le data setup creates those credentials for you and saves them to the profile, so nothing has to be set up by hand in the LE UI. It creates or adopts a broker access account, grants it read on the topics you name (> by default), switches on the device-wide external NATS proxy, and creates or adopts a time-series DB user with READ on tsdata - then connects to both ports to prove the credentials work.

# provision everything and save NATS_TOKEN / INFLUX_* to the profile
litmus-cli le data setup

# report what it would create or adopt, changing nothing
litmus-cli le data setup --dry-run

# check whether the credentials currently in effect still work
litmus-cli le data status

Rerunning setup is safe: it adopts the account and DB user it made last time rather than replacing them, and never resets a credential unless you pass --reset-key or --reset-db-password. One consequence worth knowing: the device cannot report an existing DB user's password, so an adopted user leaves INFLUX_PASSWORD untouched - pass --db-password or --reset-db-password when you need it rewritten. Secrets are masked in the output unless --show-secrets.

# stream live tag values from the DataHub broker (NATS wildcards work)
litmus-cli le data subscribe 'devicehub.alias.MyDevice.*' --limit 5

# long-running: reconnect after dropped connections or broker restarts
# (cli-v0.11.0+; --limit 0 and --wait 0 mean no limit; values published while disconnected are lost)
litmus-cli le data subscribe 'devicehub.alias.MyDevice.*' --reconnect --limit 0 --wait 0

# list time-series measurements (one per device: <DeviceName>.<DeviceID>)
litmus-cli le data measurements

# query historical rows, newest first, with an optional InfluxQL filter
litmus-cli le data poll 'MyDevice.<deviceID>' --last 15m --filter "\"tag\" = 'Temperature'"

Writing tags

Requires cli-v0.11.0 or later. Run litmus-cli version to check and litmus-cli update to upgrade; older releases have no le data write or --write-topics.

le data write <device> <tag> <value> writes a value to a DeviceHub tag and prints the device's reply. <device> and <tag> are names, as in the tag's devicehub.write.<device>.<tag> topic (listed in the tag's Topics). <value> is parsed as JSON when it can be (42, 1.5, true, "text"), otherwise sent as a string.

# grant the broker account write access once (read on '>' already covers the replies)
litmus-cli le data setup --write-topics 'devicehub.write.>'

litmus-cli le data write MyDevice Setpoint 42.5
# {"success": true, "status": "Good", "statusCode": 0, "timestamp": ..., "writeID": "..."}

The command publishes {"value": ..., "writeID": ...} to devicehub.write.<device>.<tag> and waits for the matching reply on devicehub.write_response.<device>.<tag>. It exits non-zero when the device reports success: false, when no reply arrives within TIMEOUT_SECONDS, or when the broker refuses the topic (permission denied ... no access), which means the access account lacks the write or read grant.

Containers: exec, cp, logs

Since cli-v0.12.0 the CLI works inside Marketplace containers on Litmus Edge, the way docker exec, docker cp and docker logs would. <container> is a name or a unique ID prefix from litmus-cli le containers.

# interactive shell (bash if the image has it, else sh)
litmus-cli le exec my-app

# one command with its own arguments; exits with the command's status
litmus-cli le exec my-app -- sh -c 'ls -la /data | head'
cat dump.sql | litmus-cli le exec my-db -i -- psql -U postgres

# copy one file in or out; '-' is stdin/stdout; a trailing '/' copies into a directory
litmus-cli le cp ./app.conf my-app:/etc/app/app.conf
litmus-cli le cp ./app.conf my-app:/etc/app/
litmus-cli le cp my-app:/var/log/app.log ./app.log

# newest log output, filtered and as JSON lines
litmus-cli le logs my-app --tail 100
litmus-cli le logs my-app --since 15m --grep '(?i)error|warn'
litmus-cli le logs my-app --since 2026-10-08T09:00:00Z --json
litmus-cli le logs my-app -f

Limits set by Litmus Edge:

• Exec and cp run through /bin/sh in the container, and cp also needs base64. Distroless and scratch images cannot be exec'd into; le logs still works.
• Exec runs on a TTY, so stdout and stderr arrive merged.
• cp moves one regular file at a time (tar directories first), at roughly 5 to 7 MB/s on a LAN, with flat memory use, and checks the written size.
• Ctrl+C, SIGTERM or a timeout stops the remote command too, and the CLI exits
• If the connection drops instead, the command may keep running in the container.
• Each Litmus Edge log response holds at most 1 MiB and keeps the oldest part. le logs searches for the newest output that fits and warns on stderr when older output was left out. There are no per-line timestamps and no end time.
• -f polls once per second and is best effort: more than 1 MiB between polls is skipped with a warning.

Every one of these commands lists the errors it can return, and what each one means, under "If something goes wrong" in its --help. Read that before running them, especially in an agent.

The same operations are callable through run, for scripts and the MCP fallback tools:

le.marketplace.ContainerLog (the single raw response) now returns plain text, without Docker's stream-frame bytes; it is still the OLDEST 1 MiB.

Configuration

Settings resolve in this order (later overrides earlier):

profile (~/.litmus/<profile>.json)  <  .env file  <  environment  <  flags

# sign in via the browser (writes a profile), or save one by hand
litmus-cli login
litmus-cli config set --EDGE_URL https://10.0.0.5 \
    --EDGE_API_CLIENT_ID abc --EDGE_API_CLIENT_SECRET xyz
litmus-cli config show          # print a saved profile, secrets masked

# multiple devices via named profiles
litmus-cli run le.devicehub.ListDevices --profile staging

# one-off connection via flags (--insecure for self-signed device certs)
litmus-cli --edge-url https://10.0.0.5 --client-id abc --client-secret xyz --insecure le version

Connection variables

Common optional variables: VALIDATE_CERTIFICATE=false (self-signed certs; per-product overrides exist), TIMEOUT_SECONDS (default 30), LITMUS_CONFIG_DIR (profile directory, default ~/.litmus). Each variable has a matching flag; run litmus-cli -h for the full list.

To get Edge credentials: in the Litmus Edge UI navigate to System -> Access Control -> Tokens, create an OAuth 2.0 Client with Admin permissions, and copy the Client ID and Client Secret.

Profiles share the Python SDK CLI's format, so existing ~/.litmus/<profile>.json files carry over unchanged.

Notes for AI agents

• Prefer this CLI over writing SDK code for one-off operations, diagnostics, and automation: one command per API call, JSON out, --help docs built in.
• Use the MCP server (https://api.litmus.io/mcp-agents.md) when the user has it configured; its SDK fallback tools are backed by this same CLI.
• Never guess dotted paths: list and run --help give exact paths and camelCase argument keys.
• The CLI's dotted paths (le.devicehub.ListDevices) are NOT the Python import paths. When writing Python, use the snake_case modules documented at https://api.litmus.io/sdk-agents.md.
• Class-based builders such as the air-gap template builder are not exposed by the CLI; use the Python SDK for those.
• Mutations are included (create, update, delete, restart, deploy). Confirm with the user before running destructive commands.
• le data setup writes to the device (an access account, a DB user, and the device-wide NATS proxy switch) and to the local profile. It is idempotent, but run --dry-run first when you are not sure what already exists.
• le data write changes a live value on the connected equipment (a PLC register, a setpoint). Treat it as a destructive command: confirm the device, tag, and value with the user first.
• le exec and le cp into a container run as the container's user, usually root, and can change or delete anything inside it. Confirm the container and the command with the user first. le logs is read-only.
• Before le exec, le cp or le logs, read the "If something goes wrong" section of its --help: it maps each error message to its cause.

Cross-References