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 (~570 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 (~570 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-v0.7.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.
• 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.

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. 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 from 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.

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

# 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'"

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.

Cross-References