ThingsBoard CLI User Guide + new REST Clients + Releases 4.2.2.2 and 4.3.1.2#389
Conversation
Adds a consolidated single-page user guide for the ThingsBoard CLI as a shared MDX include rendered by thin product stubs for PE, Cloud, and Cloud EU, and wires it into the AI sidebar group of each product (gated by isPE so CE does not pick it up).
Adds a "Pulling changes back from ThingsBoard" subsection covering the three calling shapes, the --solution / --dry-run / --with-credentials / --force flags, and the git-clean default safety. Also points the "UI edits are overwritten" caution and Limitations entry at tb pull as the recovery path.
ViacheslavKlimov
changed the title
The Java and Python clients track the ThingsBoard server release line, so a single TB_VER alias of CE_FULL_VER avoids the maintenance overhead of bumping per-client constants in lockstep with the platform.
Both guides are reorganized into eight task-oriented sections (Installation, Quickstart, Authentication, Rate-limit handling, Working with entities, Telemetry and attributes, Listing and querying entities, Entity groups [PE-gated], Error handling, More examples) and API signatures are verified against the live client repos. Helpers encode the CE/PE/PaaS divergence (e.g. saveDevice arity, entity group methods) so the same include serves all editions without conditional UI.
Drop the legacy REST client entries from the sidebar and card (they remain reachable via the cross-link on each new client guide), rename "Server-side Clients" to "Clients & CLI", add the CLI link with a "New" badge, and reference the CLI via slug (not raw link) so the per-version sidebar filter keeps it within its own sidebar instead of duplicating "APIs & SDKs" groups across editions.
The CLI is a separate command-line tool, not a built-in feature, so the default peFeature wording reads wrong here. Banner now supports a slot override that replaces (not appends to) the default sentence, and the new CE CLI stub uses it to render "ThingsBoard CLI works only with ThingsBoard Professional and ThingsBoard Cloud." Existing peFeature callers all use the self-closing form, so the change is backward- compatible.
ViacheslavKlimov
changed the title
The PE entity-groups Aside in the Java and Python REST client guides pointed at user-guide/entity-groups and user-guide/role-management, which don't exist — the canonical pages live at user-guide/groups and user-guide/roles.
ViacheslavKlimov
left a comment
ViacheslavKlimov
left a comment
There was a problem hiding this comment.
Review summary
Reviewed 30 changed files in ThingsBoard CLI User Guide + new REST Clients + Releases 4.2.2.2 and 4.3.1.2. Left 14 comments inline. The PR is largely well-structured — new content is thorough, the peFeature banner refactor is clean, and the release-notes/upgrade-instructions/releases-table updates are internally consistent. Main areas to double-check before merging: (1) MDX rendering bug where JSX expressions inside backticks won't evaluate, (2) whether the new edition-specific Maven/PyPI artifacts actually exist at TB_VER for PE/PaaS, (3) the test.pypi.org install command for a page marketed as New.
Additional findings
Observations about behavior outside the immediate diff lines:
src/content/_includes/docs/edge/reference/java-rest-client.mdxandpython-rest-client.mdx— The edge sidebar'sServer-side REST Clientssection is removed (bothedgeSidebarandedgePeSidebar), but the include files and their edge / edge-PE stubs still exist. They're now orphaned in the edge sidebar — reachable only by direct URL. If the intent is to retire them on the edge side, follow up with stub-file removal + redirects insrc/data/redirects.ts. If they should stay, restore the sidebar section (the deprecation<Aside>at the top of each include already steers readers to the new client).src/models/upgrade-instructions.ts:74,140— Marking only 4.3.1.1 and 4.2.2.1 asvulnerable: truewhile older 4.3.0.1 and 4.2.1.2 still don't carry the flag may be intentional (those families pre-date the CVE list in this patch), but worth a sanity check — most of the CVEs in the security section look like things older patches would also be exposed to.
This review was auto-generated. Findings may contain errors — please verify before applying changes.
- Fix MDX JSX interpolation in Python client snippets (r3280184553) - Drop test.pypi index from CLI install command (r3280184586) - Drop unused Banner prop and Fragment wrapper in CLI page (r3280184590) - Convert APIs & SDKs Clients ListCard to markdown bullets (r3280184598) - Document slot-override semantic in Banner props; render peFeature banner on Edge CE too (r3280184605) - Fix "loosing" typo in PE release notes (r3280184613) - Fix "asignee" typo and reword aggregation-keys line in release notes (r3280184618, r3280184629) - Mirror Clients & CLI on Edge sidebars with new Edge stubs; add deprecation notice on legacy Edge REST clients; add edge-aware intro wording; route shared core DocLinks via useTbDocs so Edge users land on existing pages (r3280184632) - Mark 4.3.0.1 and 4.2.1.2 as vulnerable in upgrade-instructions (pullrequestreview-4335788404)
Addressed in abf5137 — added |
Addressed in abf5137 — see the F3 reply for the full plan. The legacy Edge REST-client pages stay (now with a deprecation Aside pointing to the new Edge clients), and the new Edge sidebars have a |
There was a problem hiding this comment.
Pull request overview
Adds end-user documentation for the ThingsBoard CLI and introduces new edition-aware, OpenAPI-generated Java/Python REST client docs, while also bumping site version/release metadata for the 4.3 and 4.2 release trains.
Changes:
- Add new CLI documentation pages (CE/PE/PaaS/Edge variants) backed by a shared include.
- Add new Java/Python REST client docs and mark legacy REST client pages as deprecated.
- Update version constants, release tables/notes, sidebar navigation, banner behavior, and redirects for the new docs.
Reviewed changes
Copilot reviewed 37 out of 37 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/models/upgrade-instructions.ts | Adds upgrade entries for 4.3.1.2 and 4.2.2.2 and marks several versions as vulnerable. |
| src/models/releases-table.ts | Updates latest patch metadata and patch lists for 4.3 and 4.2 families. |
| src/data/versions.ts | Bumps CE/PE full versions and introduces TB_VER alias. |
| src/content/docs/docs/user-guide/cli.mdx | New CE CLI doc entrypoint that mounts the shared CLI include. |
| src/content/docs/docs/reference/python-client.mdx | New CE Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/reference/java-client.mdx | New CE Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/pe/user-guide/cli.mdx | New PE CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/pe/reference/python-client.mdx | New PE Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/pe/reference/java-client.mdx | New PE Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/user-guide/cli.mdx | New PaaS CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/paas/reference/python-client.mdx | New PaaS Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/reference/java-client.mdx | New PaaS Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/eu/user-guide/cli.mdx | New PaaS EU CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/paas/eu/reference/python-client.mdx | New PaaS EU Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/eu/reference/java-client.mdx | New PaaS EU Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/user-guide/cli.mdx | New Edge CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/edge/reference/python-client.mdx | New Edge Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/reference/java-client.mdx | New Edge Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/pe/user-guide/cli.mdx | New Edge PE CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/edge/pe/reference/python-client.mdx | New Edge PE Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/pe/reference/java-client.mdx | New Edge PE Java client doc entrypoint mounting the shared include. |
| src/content/_includes/docs/user-guide/cli.mdx | Adds the main CLI user guide content (shared across editions). |
| src/content/_includes/docs/releases/v4-3-x.mdx | Adds CE release notes for v4.3.1.2. |
| src/content/_includes/docs/releases/v4-2-x.mdx | Adds CE release notes for v4.2.2.2. |
| src/content/_includes/docs/reference/python-rest-client.mdx | Deprecates legacy Python REST client doc and updates install snippet. |
| src/content/_includes/docs/reference/python-client.mdx | Adds new edition-aware Python REST client documentation. |
| src/content/_includes/docs/reference/java-rest-client.mdx | Deprecates legacy Java REST client doc and updates dependency snippet. |
| src/content/_includes/docs/reference/java-client.mdx | Adds new edition-aware Java REST client documentation. |
| src/content/_includes/docs/reference/apis-and-sdks.mdx | Updates “REST Clients” card to “Clients & CLI” and links to new pages. |
| src/content/_includes/docs/pe/releases/v4-3-x.mdx | Adds PE release notes for v4.3.1.2. |
| src/content/_includes/docs/pe/releases/v4-2-x.mdx | Adds PE release notes for v4.2.2.2. |
| src/content/_includes/docs/edge/reference/python-rest-client.mdx | Adds deprecation note pointing to the new Python client docs. |
| src/content/_includes/docs/edge/reference/java-rest-client.mdx | Adds deprecation note pointing to the new Java client docs. |
| src/content/_includes/docs/edge/reference/apis-and-sdks.mdx | Updates Edge “REST Clients” card to “Clients & CLI” and links to new pages. |
| src/components/Banner.astro | Extends peFeature visibility to Edge CE and adds slot override behavior. |
| public/redirects.json | Adds redirects for new Edge PE CLI/client pages under legacy /docs/pe/edge/... paths. |
| astro.sidebar.ts | Adds CLI entries and replaces legacy REST client links with new client pages in sidebars. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
ViacheslavKlimov
left a comment
ViacheslavKlimov
left a comment
There was a problem hiding this comment.
Review summary
Reviewed 37 changed files in ThingsBoard CLI User Guide + new REST Clients + Releases 4.2.2.2 and 4.3.1.2. Left 7 comment(s) inline plus a couple of observations below.
Overall the new CLI guide and the auto-generated Java/Python REST client docs are well-structured, and the release notes additions are consistent with the existing format. The main things worth a second look are (a) the cross-cutting effect of the peFeature banner now also rendering on Edge CE pages, (b) whether the CLI doc really applies to Edge PE given the explicit Limitations wording, and (c) inconsistencies between the Edge and non-Edge variants of the new pages.
Additional findings
These are about lines outside this PR's diff, but they line up naturally with changes this PR is making:
src/content/_includes/docs/edge/reference/java-rest-client.mdx(~line 26) — still has<version>4.3.0.1</version>hardcoded. The non-Edge counterpartsrc/content/_includes/docs/reference/java-rest-client.mdxwas migrated to${TB_VER}in this PR; the Edge equivalent should follow the same migration or it'll silently fall out of sync each release. Same applies to displaying a non-current version (4.3.0.1) on a page that's now also flagged as deprecated.src/content/_includes/docs/edge/reference/python-rest-client.mdx(~line 20) —pip3 install tb-rest-clientis still unpinned. The non-Edge counterpart now pins via==${TB_VER}; same migration would keep Edge consistent.upgrade-instructions.ts—4.3.1.1,4.3.0.1,4.2.2.1, and4.2.1.2are newly markedvulnerable: true.4.2.0(an olderlts/patch: falsebaseline) is not marked. If this is the intended convention (only patch-level entries carryvulnerable), looks fine; if4.2.0should be flagged too, it's missing.
This review was auto-generated. Findings may contain errors — please verify before applying changes.
- Revert peFeature banner EDGE expansion; render only on CE (#3281128479)
- Migrate legacy edge Java REST client install snippet to ${TB_VER} (#pullrequestreview-4336868594)
- Migrate legacy edge Python REST client install to ==${TB_VER} (#pullrequestreview-4336868594)
- Align edge apis-and-sdks Clients & CLI links to CE style (bold={false}, no target) (#3281128499)
Fixed in 52f84d3 — migrated the snippet to |
Fixed in 52f84d3 — pinned to |
Convention is correct — only patch-level entries carry |
- Drop "New" badge from CLI sidebar entries (CE, PE, PaaS, PaaS EU, Edge, Edge PE) and the Clients & CLI ListCards on both apis-and-sdks pages (CE + Edge) - Add `excludeSlugs` to CatchAllRedirect; skip CLI / Java / Python client slugs when scanning the edge/pe content tree so the pe/edge catch-all no longer emits redirects nobody needs
The Entity Groups section already only renders when product is not CE and not EDGE, but the TOC plugin was injecting its three ConditionalHeading entries on Edge CE pages (productId='edge'), producing broken fragment links to anchors that don't exist in the DOM. Adding edge to the exclude list keeps the TOC in sync with the rendered body. Edge PE (productId='edge-pe') still shows both the section and its TOC entries because the exclude list is matched by exact string.
Description
Type of change
src/content/docs/**)src/content/_includes/**)src/components/**,src/styles/**)src/pages/**,src/data/**)src/data/redirects.ts)releaseskill)Affected products
Related issues
Checklist
pnpm checkpasses (Astro / TypeScript)pnpm lint:eslintpassespnpm lint:slugcheckpasses (required if pages were added/renamed/moved across languages)pnpm lint:linkcheckpasses locally — required to merge; run it before requesting review (usepnpm lint:linkcheck:nobuildif you already ran a build)src/data/redirects.ts, andpnpm generate:redirectswas runsrc/data/versions.ts