Litmus CLI Reference

19 min

litmus-cli is a standalone command-line binary that exposes the full Litmus SDK surface (~550 functions, including all mutations, Litmus Edge Manager, and Litmus Unify) without writing Python. Useful for AI agents, CI pipelines, and interactive exploration.

The CLI is no longer installed with the litmussdk Python package. It is built from the Litmus Go SDK and released on litmus-sdk-releases under cli-v* tags, with binaries for macOS arm64, Linux amd64/arm64, and Windows amd64, plus a SHA256SUMS file.

Install

macOS / Linux (recommended)

curl -fsSL https://raw.githubusercontent.com/litmusautomation/litmus-sdk-releases/main/install.sh | sh

The script detects your OS and architecture, downloads the latest cli-v* release, verifies the SHA256 checksum, and installs to ~/.local/bin. Make sure ~/.local/bin is on your PATH.

Note for macOS: install via curl as shown above. Binaries downloaded through a browser are quarantined by Gatekeeper and will refuse to run; if that happens, clear the flag with xattr -d com.apple.quarantine <path-to-binary>.

Manual install (and Windows)

Download the litmus-cli-<os>-<arch> asset for your platform from the latest cli-v* release (litmus-cli-windows-amd64.exe on Windows).

Verify it against the SHA256SUMS file from the same release.

Rename it to litmus-cli (litmus-cli.exe on Windows), make it executable, and move it into a directory on PATH (e.g. ~/.local/bin).

Once installed, the CLI can update itself in place with litmus-cli update.

If you previously used the pip-installed CLI, note that older litmussdk versions leave a litmus-sdk-cli entry point in the environment's bin/ directory. It does not conflict with the downloaded litmus-cli binary, but you can remove it by upgrading the litmussdk package.

Migrating from the pip-installed CLI

The command was renamed from litmus-sdk-cli to litmus-cli, and this is a clean break on the invocation contract: function paths and JSON argument keys differ.

Old (Python CLI)	New (Go CLI)
run devicehub.devices.list_devices	run le.devicehub.ListDevices
run lem.lifecycle.alerts.list_incidents --args '{"project_id": "X"}'	run lem.ListIncidents --args '{"projectID": "X"}'
run uns.namespace.get_namespace	run unify.GetNamespace
nested snake_case module paths	flat <product>.<package>.<PascalCaseMethod>
snake_case JSON arg keys	camelCase JSON arg keys (see list <pkg> for names)

Litmus Edge packages are grouped under the le. prefix (le.devicehub, le.system, le.analytics, le.digitaltwins, le.flows, le.integrations, le.marketplace, le.opc). lem.* and unify.* paths are unchanged.

litmus-cli list [prefix] browses every callable path with its argument names. If you pass an old-style path to run, the CLI prints a pointer to the migration guide and a suggested new path (e.g. lem.lifecycle.alerts.list_incidents suggests lem.ListIncidents), so old scripts fail with an explanation rather than silently.

Saved connection profiles are unaffected: existing ~/.litmus/<profile>.json files written by the old CLI load unchanged.

Setup

1. Configure a connection

# Browser-based sign-in; no argument shows all three product cards
litmus-cli login [le|lem|unify]

# Direct connection (OAuth2)
litmus-cli config set \
  --EDGE_URL https://<device-ip> \
  --EDGE_API_CLIENT_ID <client-id> \
  --EDGE_API_CLIENT_SECRET <client-secret>

# LEM bridge
litmus-cli config set \
  --EDGE_MANAGER_URL https://<lem-url> \
  --EDGE_API_TOKEN <token> \
  --EDGE_MANAGER_PROJECT_ID <project-id> \
  --EDGE_MANAGER_DEVICE_ID <device-id> \
  --USE_LEM_BRIDGE true

Profiles are saved to ~/.litmus/<profile>.json. The default profile is named default. To use multiple devices, pass --profile <name> to any command.

Environment variables take precedence over profiles: set EDGE_URL, EDGE_API_CLIENT_ID, EDGE_API_CLIENT_SECRET (or the LEM bridge variables) in the shell to override any saved profile.

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.

For full env var details and the three connection modes, see Managing ConnectionsManaging Connections.

Supported keys for config set:

Flag	Description
--EDGE_URL	Litmus Edge device URL
--EDGE_API_CLIENT_ID	OAuth 2.0 Client ID
--EDGE_API_CLIENT_SECRET	OAuth 2.0 Client Secret
--EDGE_MANAGER_URL	Litmus Edge Manager URL
--EDGE_MANAGER_ADMIN_URL	LEM admin URL (optional)
--EDGE_API_TOKEN	LEM API token (used by direct LEM and LEM bridge)
--EDGE_MANAGER_PROJECT_ID	LEM project ID (for bridge mode)
--EDGE_MANAGER_DEVICE_ID	LEM device ID (for bridge mode)
--USE_LEM_BRIDGE	true to route LE calls through LEM
--VALIDATE_CERTIFICATE	false to disable TLS verification
--TIMEOUT_SECONDS	Request timeout in seconds

2. (Optional) Enable tab completion

litmus-cli completion bash   # or zsh, fish, powershell

Add the printed setup line to ~/.bashrc or ~/.zshrc to persist across sessions. Completion also completes run and list dotted paths.

Commands

litmus-cli run

Call any SDK function by its dotted path. Result is JSON on stdout.

# No arguments
litmus-cli run le.devicehub.ListDevices

# With arguments (JSON object, camelCase keys)
litmus-cli run lem.ListIncidents --args '{"projectID": "X"}'

# Named profile
litmus-cli run le.devicehub.ListDevices --profile staging

# Function signature and docs, with a ready-to-fill --args skeleton
litmus-cli run le.devicehub.ListDevices --help

Litmus Edge SDK packages live under the le. prefix (le.devicehub, le.system, le.analytics, le.digitaltwins, le.flows, le.integrations, le.marketplace, le.opc); lem.* and unify.* paths have no prefix.

Results are printed as JSON on stdout; errors go to stderr. Run litmus-cli run -h for the full flag list.

litmus-cli list

Browse available packages and functions. This is the canonical way to discover what the SDK can do (~550 functions).

# List all packages
litmus-cli list

# List functions in a package, with argument names
litmus-cli list le.devicehub
litmus-cli list lem

# Print a package's SDK docs
litmus-cli list le.devicehub --help

litmus-cli config

Manage saved connection profiles.

litmus-cli config set --EDGE_URL https://10.0.0.1 --EDGE_API_CLIENT_ID id --EDGE_API_CLIENT_SECRET secret
litmus-cli config show
litmus-cli config show --profile staging   # secrets masked

Curated product commands

Beyond the generic dispatcher, common operations are grouped under product subcommands:

litmus-cli le devices        # Litmus Edge device operations
litmus-cli le data ...       # Litmus Edge data plane (live and historical tag values)
litmus-cli lem companies     # Litmus Edge Manager operations

Run litmus-cli le -h or litmus-cli lem -h to browse each group.

litmus-cli version and litmus-cli update

litmus-cli version prints the CLI's own version and build details; litmus-cli update self-updates in place to the latest cli-v* release. To get the Litmus Edge device firmware version, use litmus-cli le version.

litmus-cli completion

Print the shell completion script (bash, zsh, fish, powershell).

Run litmus-cli -h for full usage. Every command and SDK package has built-in docs via --help.

Using With AI Agents

litmus-cli is designed for use by AI agents and is the preferred method for agentic tasks. Key properties:

Structured output: results are always JSON on stdout, errors on stderr.

Discoverable: litmus-cli list enumerates every callable function.

Self-describing: litmus-cli list <package> shows argument names, and run <path> --help prints the signature with a ready-to-fill --args skeleton.

Composable: pipe JSON output to jq or any other tool.

Typical agent workflow:

# 1. Discover what's available
litmus-cli list

# 2. Inspect a package
litmus-cli list le.devicehub

# 3. Read the function docs
litmus-cli run le.devicehub.ListDevices --help

# 4. Call the function and parse the JSON result
litmus-cli run le.devicehub.ListDevices | jq '.[0].id'

Scope note: the air-gap template builder (litmussdk.airgap_features.AirGapTemplate) is class-based and Python-only; it is not exposed by the CLI. Drive it from Python and use the CLI for the surrounding live-data fetches.

The full agent guide (with package mappings and patterns) lives at api.litmus.io/cli.md.

DeviceHub Driver Records (Python package)

These helpers manage the Python SDK's own driver-record cache and still ship with the litmussdk pip package (they are unrelated to litmus-cli):

download_dh_record   # download for current EDGE_URL version
list_dh_versions     # list available cached versions
get_dh_cache_dir     # show where records are cached

litmus-cli handles driver-record downloads internally; no manual step is needed when using it.