Metadata-Version: 2.4
Name: thingsboard-cli
Version: 4.3.1.2
Summary: CLI tool for managing ThingsBoard resources
Requires-Python: <3.15,>=3.11
Requires-Dist: click<9.0,>=8.1
Requires-Dist: filelock<4.0,>=3.13
Requires-Dist: httpx<1.0,>=0.28
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic-settings<3.0,>=2.13
Requires-Dist: pydantic<3.0,>=2.12
Requires-Dist: rich<15.0,>=14.0
Requires-Dist: tb-pe-client==4.3.1.2
Requires-Dist: textual<2.0,>=0.83
Requires-Dist: typer<1.0,>=0.24.1
Description-Content-Type: text/markdown

# ThingsBoard CLI

CLI tool for managing ThingsBoard resources from the terminal.

## Installation

Install [uv](https://docs.astral.sh/uv/) if you don't have it:

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

Then install the CLI:

```bash
uv tool install thingsboard-cli
```

### Upgrading

The CLI checks for updates automatically on launch and prompts to upgrade. You can also upgrade manually:

```bash
tb update
```

### Local development

Editable install — changes take effect immediately:

```bash
uv tool install -e .
```

> **Note:** `uv tool install` overwrites any previous installation. When switching between editable and published installs, uninstall first to avoid stale cache issues:
> ```bash
> uv tool uninstall thingsboard-cli
> ```

### Updating tb-pe-client

The `tb-pe-client` dependency is pulled from PyPI and updated frequently. To pick up a new version:

```bash
uv lock --refresh-package tb-pe-client && uv sync
```

### Shell Completion

```bash
# Bash
tb --install-completion bash

# Zsh
tb --install-completion zsh

# Fish
tb --install-completion fish
```

Restart your terminal after installing completion.

## Usage

```bash
tb --help
tb config set --url https://thingsboard.cloud --api-key YOUR_KEY
tb device list
```

## Verbose Help

Use `-H` or `--help-verbose` on any command to see detailed API documentation, JSON schemas, and field descriptions:

```bash
tb device create -H
tb dashboard save -H
```

### Regenerating Help Text

After updating `tb-pe-client`, regenerate the help text from the API docs:

```bash
./scripts/generate-help.sh
```

This reads the markdown docs from `../thingsboard-java-client/pe/docs/` and generates Python modules in `src/thingsboard_cli/help/_generated/`.

## Publishing

Requires [twine](https://twine.readthedocs.io/) for uploading and credentials configured in `~/.pypirc`:

```bash
uv tool install twine
```

```bash
./scripts/release.sh --version 4.3.1.2.post1         # TestPyPI (default, staging)
./scripts/release.sh --version 4.3.1.2 --prod        # PyPI (production)
./scripts/release.sh --version 4.3.1.2 --dry-run     # Build only, no upload
```

> TestPyPI is the default on purpose — a misfire goes to staging, not to the real index. Add `--prod` only when you intend to publish a production release.

The publish script automatically updates the scaffold content hash in `scaffold/manifest.json` before building. If you change scaffold files without publishing, update the hash manually:

```bash
uv run python scripts/update_scaffold_hash.py
```

CI enforces that the hash matches — if scaffold files change but `manifest.json` isn't updated, `test_scaffold_hash_matches_manifest` will fail.
