# 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

| Layer | Guide |
|-------|-------|
| MCP Server (curated tools, no code needed) | `https://api.litmus.io/mcp-agents.md` |
| **litmus-cli (this document)** | `https://api.litmus.io/cli.md` |
| Language SDKs (Python today; Go and Rust in the works) | `https://api.litmus.io/sdk-agents.md` |
| Raw API Collection (full 2,004 endpoints) | `https://api.litmus.io/agents.md` |
| API Portal (human-readable workspace) | `https://api.litmus.io` |

---

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

```bash
# 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

| Command | Purpose |
|---------|---------|
| `litmus-cli list [prefix]` | Browse the SDK function catalog (~570 functions) with parameter names |
| `litmus-cli run <dotted.path>` | Call any SDK function by dotted path with JSON arguments |
| `litmus-cli le <shortcut>` | Curated Litmus Edge shortcuts (devices, tags, flows, containers, ...) |
| `litmus-cli le data <cmd>` | Data plane: live tag values (NATS) and time-series history (InfluxDB) |
| `litmus-cli lem <shortcut>` | Curated Edge Manager shortcuts (companies, projects, devices) |
| `litmus-cli login [le\|lem\|unify]` | Browser-based sign-in; no argument shows all three product cards |
| `litmus-cli config set/show` | Manage saved connection profiles (`~/.litmus/<profile>.json`) |
| `litmus-cli completion <shell>` | Shell completion (bash, zsh, fish, powershell); completes run/list paths too |
| `litmus-cli version` / `update` | CLI version / self-update |

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.

```bash
# 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 ...`)**

| Shortcut | What it returns |
|----------|-----------------|
| `version` | Device firmware version, API major version, bridge status |
| `system-info` | Full firmware build information |
| `devices` | DeviceHub devices with IDs, driver, running state |
| `drivers [limit]` | Driver definitions |
| `tags <deviceID> [limit]` | A device's tags/registers |
| `users` | Local user accounts |
| `dt-models` / `dt-instances` | Digital Twins models / instances |
| `analytics-groups` | Analytics processor groups |
| `processor-library` | Analytics processor types (live, falls back to embedded catalog) |
| `flows` | Node-RED flow services |
| `containers` / `images` | Marketplace containers / images |
| `providers` / `provider-catalog` / `instances` | Integration providers and connector instances |
| `opc-config` | OPC UA server configuration |
| `processor-library-defaults` / `provider-catalog-defaults` / `driver-cache-versions` | Embedded offline catalogs, no connection required |

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

| Shortcut | What it returns |
|----------|-----------------|
| `companies` | Companies visible to the API token |
| `projects <companyName>` | A company's projects |
| `devices <projectID> [status]` | A project's devices, optionally filtered (e.g. ACTIVE) |

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.

```bash
# 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
```

```bash
# 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

| Connection | Required variables |
|------------|--------------------|
| Direct to a Litmus Edge device | `EDGE_URL`, `EDGE_API_CLIENT_ID`, `EDGE_API_CLIENT_SECRET` |
| Edge via the LEM bridge | `USE_LEM_BRIDGE=true`, `EDGE_MANAGER_URL`, `EDGE_API_TOKEN`, `EDGE_MANAGER_PROJECT_ID`, `EDGE_MANAGER_DEVICE_ID` |
| Edge Manager (`lem ...`) | `EDGE_MANAGER_URL`, `EDGE_API_TOKEN` |
| Unify (`unify.*`) | `UNS_URL` plus `UNS_USERNAME`/`UNS_PASSWORD` |
| Data plane, live (`le data subscribe`) | `NATS_TOKEN` (or `NATS_USER`/`NATS_PASSWORD`); optional `NATS_SOURCE`, `NATS_PORT`, `NATS_TLS` |
| Data plane, historical (`le data poll`) | `INFLUX_USERNAME`, `INFLUX_PASSWORD`; optional `INFLUX_HOST`, `INFLUX_PORT`, `INFLUX_DB_NAME`, `INFLUX_SSL` |

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

| Need | Go to |
|------|-------|
| Download the binary | `https://github.com/litmusautomation/litmus-sdk-releases/releases` (cli-v* tags) |
| CLI and SDK navigation guide for LLMs | `https://api.litmus.io/sdk-agents.md` |
| MCP server (tool calls, no shell) | `https://api.litmus.io/mcp-agents.md` |
| Raw API collection | `https://api.litmus.io/agents.md` |
| Report a bug or request a feature | `https://github.com/litmusautomation/litmus-sdk-releases/issues` |
| Product docs | `https://docs.litmus.io` |