Getting Started

13 min

This page walks you from a fresh environment to your first SDK call. For deeper coverage of authentication and multi-device workflows, see Managing ConnectionsManaging Connections.

1. Install

The SDK ships as a standalone wheel from the releases repo. Download the latest .whl and install it:

pip install litmussdk-*.whl

All runtime dependencies are bundled in the wheel; no extra installs are needed.

Requirements: Python 3.12 or newer.

2. Generate Credentials

In your Litmus Edge UI:

Navigate to System -> Access Control -> Tokens

Press + next to API Credentials and select OAuth 2.0 Client

Grant Admin permissions (lesser permissions are supported but may limit SDK functionality)

Copy the Client ID and Client Secret

For more detail see the Create an API TokenCreate an API Token.

3. Configure

Set environment variables (or place them in a .env file in your working directory; both are loaded automatically):

export EDGE_URL=https://<your-edge-ip>
export EDGE_API_CLIENT_ID=<client-id>
export EDGE_API_CLIENT_SECRET=<client-secret>

If your device uses a self-signed TLS certificate (common in edge deployments), also set:

export VALIDATE_CERTIFICATE=false

For LEM-bridged or direct LEM connections, see Managing ConnectionsManaging Connections.

4. First Call

from litmussdk.devicehub import devices

# Uses the default connection from environment variables
all_devices = devices.list_devices()
print(all_devices)

Each Device is a Pydantic model. Pass raw=True to get the API JSON unchanged instead:

all_raw = devices.list_devices(raw=True)  # list[dict[str, Any]]

5. CLI Quick Start

litmus-cli is a standalone command-line binary (no longer installed with the litmussdk package) that exposes the full SDK surface as shell commands with JSON output. Useful for scripting, CI pipelines, and AI agents. It reads the same environment variables and ~/.litmus/<profile>.json profiles as the Python SDK.

Install

The recommended path on macOS and Linux is the install script:

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 from the releases repo, verifies the SHA256 checksum, and installs to ~/.local/bin. Make sure ~/.local/bin is on your PATH. Installing via curl also avoids the macOS Gatekeeper quarantine that blocks binaries downloaded through a browser.

On Windows, download litmus-cli-windows-amd64.exe from the latest cli-v* release and put it on PATH. Once installed, litmus-cli update self-updates in place.

Discover and run

# Discover available functions
litmus-cli list                    # all packages
litmus-cli list le.devicehub       # functions in one package, with argument names

# Call a function (result as JSON on stdout)
litmus-cli run le.devicehub.ListDevices
litmus-cli run le.devicehub.ListAllTags --args '{"limit": 50}'

Note that the CLI's dotted paths (le.devicehub.ListDevices) are not the Python import paths, and argument keys are camelCase. See Litmus CLI ReferenceLitmus CLI Reference for the full command set and the migration table from the old litmus-sdk-cli.

DeviceHub Driver Records

The SDK ships with bundled DeviceHub driver record templates used during device validation. If you need records for a specific Litmus Edge version not covered by the bundled set, use the helper commands installed with the litmussdk package:

download_dh_record   # download templates for the configured EDGE_URL version
list_dh_versions     # list available bundled versions
get_dh_cache_dir     # show where templates are cached

(litmus-cli downloads driver records automatically when needed; no manual step is required there.)