---
title: Getting Started
slug: sdk/getting-started
description: Python module that allows users to easily interface with the Litmus product APIs.
docTags: 
createdAt: 2025-03-20T19:51:20.571Z
---

This page walks you from a fresh environment to your first SDK call. For deeper coverage of authentication and multi-device workflows, see [Managing Connections](docId\:vwtFo9SXcMRbFX9cAfENw).

***

## 1. Install

The SDK ships as a standalone wheel from the [releases repo](https://github.com/litmusautomation/litmus-sdk-releases/releases). Download the latest `.whl` and install it:

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

1. Navigate to **System -> Access Control -> Tokens**
2. Press **+** next to *API Credentials* and select **OAuth 2.0 Client**
3. Grant **Admin** permissions (lesser permissions are supported but may limit SDK functionality)
4. Copy the **Client ID** and **Client Secret**

For more detail see the [Create an API Token](docId\:lVnOQKsvR3JrihSoOxaHr).

***

## 3. Configure

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

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

```bash
export VALIDATE_CERTIFICATE=false
```

For LEM-bridged or direct LEM connections, see [Managing Connections](docId\:vwtFo9SXcMRbFX9cAfENw).

***

## 4. First Call

```python
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:

```python
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:

```bash
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](https://github.com/litmusautomation/litmus-sdk-releases/releases), 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

```bash
# 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 Reference](docId\:s7O-dG4pyackxxPsOJ2Qf) 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:

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

***

## License

Copyright (c) Litmus Automation Inc.