Getting Started with CLI

ThingsBoard CLI is a command-line tool (thingsboard, alias tb) for managing your ThingsBoard resources from the terminal. There are two ways to use it:

• Let Claude drive it. Run tb init to scaffold a project on disk with built-in Claude Code skills. Open the project, describe the solution you want, review what Claude produced, then run tb push to deploy.
• Drive it yourself. Run tb device save, tb dashboard save, tb push, and other commands directly — for scripting, CI, or one-off tasks. No Claude required.

• Project — your local workspace for designing and managing ThingsBoard solutions. Create one with tb init in any folder; that folder becomes the project root — where the CLI reads and writes entity files, and where Claude builds solutions.
• Solution — a self-contained collection of devices, dashboards, alarm rules, and other entities that work together to solve one business need (a smart house, a fleet, a factory line). A single project can hold many solutions, and the same solution can be deployed to multiple ThingsBoard targets (dev, staging, prod) without any changes.
• Profile — a saved connection to a ThingsBoard instance: a URL and authentication credentials stored under a name of your choice (cloud, prod, staging). The active profile determines which instance your commands target; pass --profile <name> to any command to override it for that call.

• A ThingsBoard account — ThingsBoard Cloud or a self-hosted ThingsBoard Professional instance.
• An API key with CRUD permissions for the resources the CLI will manage.

1. Install uv.
   uv is a fast Python package manager that handles the CLI’s virtual environment for you.

   curl -LsSf https://astral.sh/uv/install.sh | sh

   See the uv installation guide for platform-specific options.

2. Install the CLI.

   uv tool install thingsboard-cli

   This installs the thingsboard command and its tb alias on your system.

3. Verify the installation.

   tb --version

Run the interactive wizard:

tb config

The wizard asks:

ThingsBoard URL [https://thingsboard.cloud]:
Auth method [api_key]:
API Key: ********
Profile name: cloud

• ThingsBoard URL. Defaults to https://thingsboard.cloud — press Enter to connect to ThingsBoard Cloud. If ThingsBoard is deployed elsewhere, enter its URL (e.g. https://eu.thingsboard.cloud for Cloud EU, or your own host for self-hosted ThingsBoard PE).
• Auth method. Defaults to api_key — press Enter to accept. This is the recommended method. The alternative jwt saves your username and password to the profile file in plaintext; the CLI will warn you and recommend API key auth instead.
• API Key. Enter your API key. You can generate one in ThingsBoard under Account ⇾ Security ⇾ API keys — see API Keys for details.
• Profile name. Enter a name for this profile. Choose any name that makes sense — cloud, cloud-eu, prod, etc.

On success, the wizard prints:

Profile '<name>' saved. Connected to <url>

If the connectivity test fails, the CLI still saves the profile but prints a warning. Re-run tb config to fix the URL or key, or run tb config show to confirm what’s active.

For scripting and CI, skip the wizard and use the one-shot form:

tb config set --url <url> --api-key <key>

Profiles are additive — you can create and manage as many as you need:

tb config list                                       # show all profiles
tb config use prod                                   # switch the default profile
tb config add staging --url https://... --api-key ...
tb config remove staging

Pass --profile <name> to any command to override the active profile for that single call.

mkdir my-iot-project && cd my-iot-project && tb init

tb init creates the following project structure:

my-iot-project/
  thingsboard.json         # project config
  .gitignore
  .git/                    # git repository (initialized if not already inside one)
  devices/                 # entity directories — one JSON file per entity
  device-profiles/
  dashboards/
  rule-chains/
  customers/
  calculated-fields/
  ...
  solutions/               # solutions live here, one subdirectory per solution
  tasks/                   # synthetic-telemetry generators
  .claude/                 # Claude Code skills bundled with the CLI

Open the project in Claude Code:

claude --model sonnet

The bundled .claude/ skills load automatically — Claude is ready to design and deploy solutions as soon as you open the project.

The CLI has two operating modes:

• Local mode — the default after tb init. Commands like tb device save write the resource to your project files on disk; nothing reaches ThingsBoard until you run tb push. This is what enables managing your tenant as code, multi-target deployments, and version control of your solutions.
• Remote mode — tb device save and other write commands call the ThingsBoard API directly and apply changes immediately. No project files are written.

Mode is a per-project setting. Switch it at any time:

tb config mode remote    # turn the current project into remote mode
tb config mode local     # switch back to the default local mode

To force a single command to call the API directly without changing the project’s mode, add --remote:

tb device save --remote --json '{"name": "Sensor-01", "type": "Temperature Sensor"}'

The CLI’s own help is always up to date and is the canonical reference for every command.

tb --help                # top-level command groups
tb device --help         # subcommands inside a group
tb device save --help    # flags and options for one command

For any command that maps to a ThingsBoard API method, append -H (or --help-verbose) to see the full request schema, including which fields are required, which are read-only, and the underlying API method name:

tb device save -H

Claude Code uses verbose help internally to discover schemas. Humans benefit from it too — it answers most “what JSON do I need to pass?” questions on the spot.

# List devices
tb device list

# Create a device by passing a JSON body
tb device save --json '{"name": "Sensor-01", "type": "Temperature Sensor"}'

# Or use the shorthand flags for common fields
tb device save --name Sensor-02 --type "Temperature Sensor"

# Save server-scope attributes on an entity
tb attributes save DEVICE 16216cd0-4f85-11f1-b03b-97f809988331 --scope SERVER_SCOPE --json '{"firmwareVersion": "1.0.3"}'

Every entity type has its own group (tb dashboard, tb asset, tb customer, tb rule-chain, tb calculated-field, …) with the same list / save / delete shape.

Install completion once and restart your terminal:

tb --install-completion bash    # bash
tb --install-completion zsh     # zsh
tb --install-completion fish    # fish