Getting Started with CLI

ThingsBoard CLI is a command-line tool (thingsboard, alias tb) for managing your ThingsBoard resources from the terminal. This page covers installation and initial setup. Once that’s done, you can build complete IoT solutions by having Claude Code drive the CLI — see Build IoT Solutions with ThingsBoard CLI for the full workflow.

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