@thinger-io/cli 0.0.0-stage → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## [0.2.2] - 2026-10-12
+
+### Changed
+
+- First release of `@thinger-io/cli` from GitHub Actions (Trusted Publishing,
+  with provenance); 0.2.1 was published by hand to create the package.
+
+## [0.2.1] - 2026-10-12
+
+### Changed
+
+- Published as `@thinger-io/cli` (formerly `@thinger-io/thinger-cli`, now
+  deprecated). The command is still `thinger` and profiles stay in
+  `~/.config/thinger-cli`.
+
+## [0.2.0] - 2026-10-10
+
+### Changed
+
+- Requires `@thinger-io/cli-core` 0.2.0: the MCP server goes from 48 tools to
+  23 (`thinger_resource_*` over a catalog of resource types, plus the
+  operations that are not CRUD), less than half the size in `tools/list`.
+  Tool names change: `thinger_devices` → `thinger_resource_list` with
+  `type: "device"`, `thinger_profiles` → `thinger_profile_list`,
+  `thinger_bucket_read` → `thinger_bucket_data_read`, and so on.
+- MCP instructions rewritten for the new tools.
+
+
+## [0.1.1] - 2026-10-10
+
+### Changed
+
+- Requires `@thinger-io/cli-core` 0.1.1. First release published from GitHub
+  Actions through Trusted Publishing.
+
+## [0.1.0] - 2026-10-10
+
+First version: the `thinger` CLI, built on
+[@thinger-io/cli-core](https://github.com/thinger-io/thinger-cli-core) (the generic
+core of ThinRemote's `thinr`, made independent of the product).
+
+### Added
+
+- Thinger identity: profiles in `~/.config/thinger-cli`, `THINGER_PROFILE` /
+  `THINGER_INSECURE`, MCP tools as `thinger_*`.
+- `login` with username/password (mints the `thinger_cli` API token), an
+  existing token (non-interactive with `--server --username --token`) or the
+  OAuth device flow with a client registered on the server.
+- `logout` forgets the current profile (or `--all`) and revokes the API token
+  the CLI created.
+- Commands: `device` (list, info, create, delete, set-product, property,
+  property-set, resource), `product` (list, info, create, delete,
+  property-list, property-get, property-set, property-delete), `bucket` (list,
+  read), `profile`.
+- `thinger mcp`: devices, resources, properties, products, product profiles,
+  buckets, tokens, alarms and profiles.

package/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025 Thinger.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# thinger — Thinger.io CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A command-line tool for any [Thinger.io](https://thinger.io) server, and an
+MCP server that lets AI assistants (Claude Code, Claude Desktop, Cursor…)
+operate it with the permissions of your token.
+
+- **CLI** — devices, products, buckets and profiles from a shell, with
+  `--json` output for scripts.
+- **MCP server** — `thinger mcp` serves 23 `thinger_*` tools over
+  stdio.
+
+Both share the same profiles and API layer: sign in once, use either.
+
+> Interim tool. The long-term Thinger MCP is built into the server itself;
+> until then this CLI gives every Thinger server an MCP today.
+
+## Installation
+
+```bash
+npm install -g @thinger-io/cli
+# or, from source
+git clone https://github.com/thinger-io/thinger-cli.git && cd thinger-cli && npm install && npm link
+```
+
+Requires Node.js 20 or newer.
+
+## Signing in
+
+```bash
+thinger login                       # interactive: username/password, token or OAuth
+thinger login --server acme.aws.thinger.io --username alice --token <API token>
+```
+
+- **Username and password** — creates (or replaces) an API token named
+  _Thinger CLI_ (id `thinger_cli`) on your account and stores it. `thinger
+logout` revokes it.
+- **Token** — paste an existing API token; it is validated and stored as is.
+- **OAuth** — browser device flow. Needs an OAuth client registered on the
+  server (`--client-id`); Thinger servers ship none by default yet.
+
+The server is a host (`acme.aws.thinger.io`, HTTPS) or a full URL for plain
+HTTP or custom ports (`http://localhost:8080`). Self-signed certificates are
+accepted for `localhost`, or anywhere with `THINGER_INSECURE=1`.
+
+## Profiles
+
+Each profile is a server plus its credentials, stored in
+`~/.config/thinger-cli/config.json` (mode 600).
+
+```bash
+thinger profile add staging        # sign in to another server
+thinger profile list
+thinger profile use staging        # change the default
+thinger --profile staging device list
+THINGER_PROFILE=staging thinger device list
+```
+
+`-u, --user <account>` addresses another account on the same server when
+your profile has admin rights.
+
+## Commands
+
+```bash
+thinger device list [pattern]                  # regex on id/name
+thinger device info <id>
+thinger device create <id> [-t Generic|MQTT|HTTP|Virtual|Subdevice] [-p product]
+thinger device delete <id> [-y]
+thinger device set-product <id> <product>
+thinger device property <id> [property] [-f dot.path]
+thinger device property-set <id> <property> <json>
+thinger device resource <id> [resource] [-i key=value …]
+
+thinger product list | info <id> | delete <id>
+thinger product create <id> [--from product.json]   # { config, profile }
+thinger product property-list <id>
+thinger product property-get <id> <property>
+thinger product property-set <id> <property> <json>
+thinger product property-delete <id> <property>
+
+thinger bucket list
+thinger bucket read <bucket> [-d device] [-n 10] [-m minutes] [--agg 5m --agg-type mean]
+```
+
+Every command takes `-j, --json` and then prints `{ ok, data }` or
+`{ ok: false, error: { message, code } }`.
+
+## MCP server
+
+```bash
+claude mcp add thinger -- thinger mcp
+# without installing it: claude mcp add thinger -- npx -y @thinger-io/cli mcp
+# from source: claude mcp add thinger -- node /path/to/thinger-cli/bin/thinger.js mcp
+```
+
+Other hosts take the same command (`thinger`, args `["mcp"]`), or
+`npx` with args `["-y", "@thinger-io/cli", "mcp"]`.
+
+Tools:
+
+- `thinger_resource_describe`, `_list`, `_get`, `_create`, `_update`,
+  `_delete`, `_clone`, `_call` — every server resource by `type`: devices,
+  products, buckets, dashboards, endpoints, storages, asset types and
+  groups, projects and their members, tokens, alarms, claims, properties,
+  their children, and the server's administration (users, hosts, domains,
+  brands, OAuth clients, identity providers, proxies). `resource_call` runs
+  actions such as verifying a domain, calling an endpoint or testing an
+  alarm rule. `resource_describe` shows a type's fields, examples and
+  actions, read from the server's own API description.
+- `thinger_bucket_data_read` / `_write`, `thinger_device_resource_list` /
+  `_call`, `thinger_device_data_send`, `thinger_device_overview`,
+  `thinger_product_resource_call`, `thinger_storage_file_list` / `_read` /
+  `_write` / `_delete`, `thinger_dashboard_publish`, `thinger_doc_read`,
+  `thinger_profile_list`.
+
+Every tool takes an optional `profile`, and most an optional `user`.
+
+## Shared core
+
+Everything that is not Thinger-specific — API client, auth, profiles, REST
+helpers, the generic commands and the MCP tools — lives in
+[@thinger-io/cli-core](https://github.com/thinger-io/thinger-cli-core). This CLI only
+supplies its identity (`lib/identity.js`): binary name, config folder,
+environment prefix, the token the password login creates, OAuth client and
+MCP tool prefix. ThinRemote's `thinr` is built on the same core with its own
+identity, so the two keep separate profiles and tool names and can run side
+by side.
+
+## Development
+
+```bash
+npm install
+npm test           # node --test
+npm run lint
+npm run typecheck
+```
+
+## License
+
+MIT

package/bin/thinger.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { defineIdentity } from '@thinger-io/cli-core/identity';
+import { runCli } from '@thinger-io/cli-core/cli';
+import { mcpInstructions, thingerIdentity } from '../lib/identity.js';
+
+// Single source of truth for the version: package.json.
+const pkg = JSON.parse(
+    readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8'),
+);
+
+defineIdentity(thingerIdentity);
+await runCli({ version: pkg.version, mcpInstructions });

package/lib/identity.js

@@ -0,0 +1,36 @@
+// @ts-check
+
+/**
+ * Identity of the `thinger` CLI. This is the only Thinger-specific piece:
+ * everything else comes from @thinger-io/cli-core, shared with other CLIs
+ * built on it (thinr), which pass their own identity.
+ *
+ * Profiles live apart from thinr's (~/.config/thinr-cli, THINR_*) on
+ * purpose, so neither CLI's MCP server operates on the other's servers.
+ *
+ * @type {import('@thinger-io/cli-core/identity').CliIdentity}
+ */
+export const thingerIdentity = {
+    name: 'thinger',
+    displayName: 'Thinger.io',
+    description:
+        'CLI for Thinger.io servers — devices, products, buckets, with an MCP server for AI clients',
+    configDir: 'thinger-cli',
+    envPrefix: 'THINGER',
+    token: { id: 'thinger_cli', name: 'Thinger CLI' },
+    // No OAuth client ships with Thinger servers yet: the browser login asks
+    // for one registered on the instance.
+    oauth: { clientId: null },
+    defaultServer: null,
+    mcp: { serverName: 'thinger', toolPrefix: 'thinger' },
+};
+
+/** Server-level guidance sent to MCP clients on `initialize`. */
+export const mcpInstructions = `Tools to operate a Thinger.io IoT server with the permissions of the token stored in the CLI profile.
+
+- Server resources (devices, products, buckets, dashboards, tokens, alarms, properties…) are reached through thinger_resource_list / _get / _create / _update / _delete / _clone with a \`type\`. Start with thinger_resource_describe without arguments: it lists the types and, on servers that publish it, explains the platform's concepts (which data source fits each need, recipes). With a type it gives its fields and examples: call it before writing one for the first time.
+- List before acting to discover ids (thinger_resource_list with type "device", "product", "bucket"…); never guess them.
+- Device resources (the API a connected device's firmware exposes) are a different thing: thinger_device_resource_list / thinger_device_resource_call.
+- Custom dashboards are HTML apps using the server's dashboard SDK: publish them with thinger_dashboard_publish (thinger_resource_describe type "dashboard" has the SDK reference).
+- Every tool takes an optional \`profile\` (another configured server, see thinger_profile_list) and most take \`user\` (another account, admin only).
+- Destructive tools (delete, overwrite) act immediately: confirm with the user first.`;

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "@thinger-io/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@thinger-io/cli",
+    "version": "0.2.2",
+    "description": "CLI for Thinger.io servers — devices, products, buckets — with an MCP server for AI clients",
+    "main": "bin/thinger.js",
+    "bin": {
+        "thinger": "bin/thinger.js"
+    },
+    "files": [
+        "bin",
+        "lib",
+        "CHANGELOG.md",
+        "LICENSE",
+        "README.md"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/thinger-io/thinger-cli.git"
+    },
+    "bugs": "https://github.com/thinger-io/thinger-cli/issues",
+    "homepage": "https://github.com/thinger-io/thinger-cli#readme",
+    "scripts": {
+        "start": "node bin/thinger.js",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "typecheck": "tsc",
+        "test": "node --test 'tests/**/*.test.js'"
+    },
+    "keywords": [
+        "cli",
+        "iot",
+        "thinger",
+        "thinger.io",
+        "mcp"
+    ],
+    "author": "Thinger.io",
+    "license": "MIT",
+    "dependencies": {
+        "@thinger-io/cli-core": "^0.2.0"
+    },
+    "type": "module",
+    "engines": {
+        "node": ">=20"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/node": "^25.6.0",
+        "eslint": "^10.2.0",
+        "eslint-config-prettier": "^10.1.8",
+        "globals": "^17.5.0",
+        "prettier": "^3.8.3",
+        "typescript": "^6.0.2"
+    }
+}