@thinger-io/cli 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## [0.5.0] - 2026-10-31
+
+Every command follows one grammar, noun first:
+`thinger <noun> [<noun>…] <verb> [<parent ids>…] [<id>] [options]`.
+Nouns nest under their parent (`device property`, `product profile api`),
+ids are positional and named after their noun, and the options keep one
+meaning everywhere (`-j` JSON, `-s` a body field, `-f` one field of the
+answer, `-o` a file, `-y` no questions). A few commands of 0.3 change
+form: see the table below. The old forms are gone, not aliased.
+
+The MCP server serves eight tools instead of 25: `thinger_resource_*`
+reach everything by `type`, and records are addressed with `ids`. The old
+tool names and the `parent`/`id` arguments are gone, not aliased: see the
+second table below.
+
+### Added
+
+- Commands for every resource type the MCP server reaches, generated from
+  the same catalog: `list|get|create|update|delete|clone|describe` and the
+  type's actions (`thinger endpoint call`, `thinger alarm rule test`,
+  `thinger admin host restart`…), with bodies from `--from` and
+  `-s key=value`, `-n`/`-d` for the name and description, and
+  `set <property> <value>` on every kind of property. Endpoints, tokens,
+  alarms, storages, projects, assets, syncs, claims, plugins, product
+  profiles, properties and the server administration are now reachable from
+  the command line and from CI.
+- `thinger api <path>`: any request to the server, as `gh api` does.
+- Commands over the operations that are not CRUD:
+  `thinger bucket write|export`,
+  `thinger storage file list|upload|download|delete`,
+  `thinger device send|overview`, `thinger device resource list|call`,
+  `thinger product apply --from`, `thinger product profile api call` and
+  `thinger plugin call`. `product export` and `product apply` keep a
+  product in a repository and deploy it.
+- `device list`, `product list` and `bucket list` take `--search`,
+  `--filter`, `--count` and `--index`; `device create` and `product create`
+  take `--from`, `-s` and `--projects`; `get` takes `-f <dot.path>`.
+- `thinger doc list` and `thinger doc get <doc>`: the guides for agents
+  from the command line.
+- MCP: `resource_describe` shows each type's ids, actions, the permission
+  each operation needs and ready-to-send examples; actions that change a
+  lot at once (`replace_all`, a host's settings or restart, removing a
+  plugin) answer a plan and run with `confirm: true` (or ask through the
+  client when it supports it); `thinger mcp --read-only` (or
+  `THINGER_MCP_READ_ONLY=1`) serves only what reads.
+
+### Changed (breaking)
+
+| 0.3                                              | 0.4                                                         |
+| ------------------------------------------------ | ----------------------------------------------------------- |
+| `thinger device list <pattern>`                  | `thinger device list --search <text>`                       |
+| `thinger device info <device>`                   | `thinger device get <device>`                               |
+| `thinger device property <device>`               | `thinger device property list <device>`                     |
+| `thinger device property <device> <prop>`        | `thinger device property get <device> <property>`           |
+| `thinger device property-set <device> <p> <v>`   | `thinger device property set <device> <property> <value>`   |
+| `thinger device resource <device>`               | `thinger device resource list <device>`                     |
+| `thinger device resource <device> <r> -i k=v`    | `thinger device resource call <device> <resource> -s k=v`   |
+| `thinger product info <product>`                 | `thinger product get <product>`                             |
+| `thinger product property-list <product>`        | `thinger product property list <product>`                   |
+| `thinger product property-get <product> <p>`     | `thinger product property get <product> <property>`         |
+| `thinger product property-set <product> <p> <v>` | `thinger product property set <product> <property> <value>` |
+| `thinger product property-delete <product> <p>`  | `thinger product property delete <product> <property> -y`   |
+
+- `device property get` and `product property get` print the property
+  record, with its value under `value`: `-f` paths start there
+  (`-f value.setpoint` where 0.3 took `-f setpoint`). `device property list`
+  and `product property list` print the records (`-j`: the records, not
+  `{ product, properties: [names] }`). `product property delete` asks
+  unless `-y`. `device resource call` takes its input from `--from` and
+  `-s` (`-i` is gone); `-s` values are parsed as JSON, as before.
+- The root help groups the commands as Resources, Administration,
+  Configuration and Integration.
+- The MCP tools (the commands keep their forms and `-j` outputs; the help
+  names some positionals as the server does: `asset type get <type>`,
+  `asset group get <group>`, `alarm rule get <rule>`,
+  `alarm instance get <instance>`,
+  `product profile <category> get <product> <resource>`):
+
+| 0.3 tool                                         | 0.4 call                                                                                  |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `thinger_resource_* parent "d1" id "p1"`         | `thinger_resource_* ids {"device": "d1", "property": "p1"}`                               |
+| `thinger_bucket_data_read`                       | `thinger_resource_list type "bucket_data" ids {bucket}` (`filter` for the query)          |
+| `thinger_bucket_data_write`                      | `thinger_resource_create type "bucket_data" ids {bucket} body <samples>`                  |
+| `thinger_storage_file_list`                      | `thinger_resource_list type "storage_file" ids {storage} filter {path}`                   |
+| `thinger_storage_file_read`                      | `thinger_resource_get type "storage_file" ids {storage, file}`                            |
+| `thinger_storage_file_write`                     | `thinger_resource_create type "storage_file" ids {storage, file} body {content or local}` |
+| `thinger_storage_file_delete`                    | `thinger_resource_delete type "storage_file" ids {storage, file}`                         |
+| `thinger_device_resource_list`                   | `thinger_resource_list type "device_resource" ids {device}`                               |
+| `thinger_device_resource_call`                   | `thinger_resource_call type "device_resource" action "call" ids {device, resource}`       |
+| `thinger_device_data_send`                       | `thinger_resource_call type "device" action "send" ids {device} body <data>`              |
+| `thinger_device_overview`                        | `thinger_resource_call type "device" action "overview"`                                   |
+| `thinger_product_resource_call`                  | `thinger_resource_call type "product_profile_api" action "call" ids {product, resource}`  |
+| `thinger_plugin_call`                            | `thinger_resource_call type "plugin" action "call" ids {plugin} body {path, method}`      |
+| `thinger_doc_read`                               | `thinger_resource_get type "doc" ids {doc}` (`thinger_resource_list type "doc"` lists)    |
+| `thinger_profile_list`                           | `thinger_resource_list type "profile"`                                                    |
+| `thinger_dashboard_init` / `_dev` / `_publish`   | `thinger_resource_call type "dashboard" action "init"` / `"dev"` / `"publish"`            |
+
+- Requires `@thinger-io/cli-core` 0.5.0. From this release the CLI's minor
+  version follows the core's (0.5.x runs on cli-core 0.5.x), so there is no
+  0.4.0.
+
+
+### Fixed
+
+- Tokens created with an expiry such as "30d" (`thinger_resource_create`)
+  were refused by the server: it takes milliseconds.
+
 ## [0.3.0] - 2026-10-16
 
 ### Added

package/README.md

@@ -6,8 +6,8 @@ operate it with the permissions of your token.
 
 - **CLI** — devices, products, buckets, dashboard apps and profiles from a
   shell, with `--json` output for scripts.
-- **MCP server** — `thinger mcp` serves 25 `thinger_*` tools over
-  stdio.
+- **MCP server** — `thinger mcp` serves eight `thinger_resource_*` tools
+  over stdio.
 
 Both share the same profiles and API layer: sign in once, use either.
 
@@ -65,25 +65,86 @@ profile unless `--profile` or `THINGER_PROFILE` names one, and
 
 ## Commands
 
+Every command reads the same way: nouns, then a verb, then the ids,
+outermost first.
+
+```
+thinger <noun> [<noun>…] <verb> [<parent ids>…] [<id>] [options]
+```
+
 ```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 device list [--search sensor] [--filter product=meteo]
+thinger device get <device> [-f connection.active]
+thinger device create <device> [-t Generic|MQTT|HTTP|Virtual|Subdevice] [-p product] [-n name]
+thinger device update <device> [-n name] [-s key=value …] [--from device.json]
+thinger device delete <device> [-y]
+thinger device set-product <device> <product>
+thinger device property list <device>
+thinger device property get <device> <property> [-f value.setpoint]
+thinger device property set <device> <property> <json>
+thinger device resource list <device>
+thinger device resource call <device> <resource> [-s key=value …] [-f field]
+thinger device send <device> -s temperature=21.5     # as an HTTP device
+thinger device bucket tag list <device> <bucket>
+
+thinger product list | get <product> | delete <product>
+thinger product create <product> [--from product.json]   # { config, profile }
+thinger product property list|get|set|delete <product> [property] [value]
+thinger product profile api list <product>
+thinger product profile bucket create <product> <bucket> --from bucket.json
+thinger product profile api call <product> <resource> [--from payload.json]
+thinger product export <product> -o product.json
+thinger product apply --from product.json      # create or update: profile, properties
 
 thinger bucket list
 thinger bucket read <bucket> [-d device] [-n 10] [-m minutes] [--agg 5m --agg-type mean]
+thinger bucket write <bucket> --from samples.ndjson     # or -s temperature=21.5
+thinger bucket export <bucket> -o data.csv [--format csv|json|arff]
+thinger bucket export-file list <bucket>
+
+thinger storage file list <storage> [folder]
+thinger storage file upload <storage> ./dist [--to web]
+thinger storage file download <storage> <path> [-o file]
+thinger storage file delete <storage> <path> [-y]
+
+thinger plugin call <plugin> [path] [-X post] [--from body.json]
+```
+
+Every resource type the MCP server reaches has its commands, generated from
+the same catalog, with the verbs it supports and its actions. Child types
+nest under their parent (`device property`, `device bucket tag`,
+`product profile api`, `project member`, `sync lock`) and server types go
+under `admin`:
+
+```bash
+thinger <noun…> list [parents…] [--search text] [--filter key=value] [--count n]
+thinger <noun…> get [parents…] <id> [-f dot.path] [-o file]
+thinger <noun…> create [parents…] [id] [-n name] [-d text] [--from file.json] [-s key=value …]
+thinger <noun…> update [parents…] <id> [--from file.json] [-s key=value …] [--merge]
+thinger <noun…> delete [parents…] <id> [-y]
+thinger <noun…> clone [parents…] <id> <new-id>
+thinger <noun…> set [parents…] <property> <json>   # properties only
+thinger <noun…> describe                          # fields and examples, from the server
+thinger <noun…> <action> [parents…] [id] [--from file.json] [-q key=value]
+
+thinger endpoint call notify -s message=hello
+thinger token create ci -n CI -s expire='"30d"' -s 'allow={"Device":{"*":"*"}}'
+thinger alarm rule test overheat
+thinger device property update boiler setpoint -s value.target=21 --merge
+thinger asset type property set boiler max_temp 90
+thinger admin host get-settings <host>              # server types, for admins
+```
+
+`-s` values are parsed as JSON when they are (`21`, `true`, `{"a":1}`;
+quote strings that look like numbers: `-s code='"007"'`) and dots nest
+(`-s data.source=resource`).
+
+Anything else the API offers, with `thinger api` (`{user}` is the account):
+
+```bash
+thinger api /v1/users/{user}/products/boiler/firmwares
+thinger api -X PUT /v1/users/{user}/devices/sensor1 -s enabled=false
+thinger api /v2/users/{user}/storages/web/files/logo.png -o logo.png
 ```
 
 Every command takes `-j, --json` and then prints `{ ok, data }` or
@@ -190,27 +251,36 @@ claude mcp add thinger -- thinger 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_plugin_call`,
-  `thinger_storage_file_list` / `_read` / `_write` / `_delete`,
-  `thinger_dashboard_init` / `_dev` / `_publish`, `thinger_doc_read`,
-  `thinger_profile_list`. `thinger_dashboard_dev` gives an agent the dev
-  link above: with browser tools it opens the app, reads its console and
-  iterates, then publishes it once.
-
+Tools: `thinger_resource_describe`, `_list`, `_get`, `_create`,
+`_update`, `_delete`, `_clone` and `_call` (actions). Each takes a `type`
+and the record's `ids`, one key per level (`{"device": "d1"}`,
+`{"device": "d1", "property": "setpoint"}`,
+`{"product": "p1", "resource": "temp"}`):
+
+- The server's resources: devices, products, buckets, dashboards,
+  endpoints, storages, asset types and groups, projects and their members,
+  tokens, alarms, claims, plugins, properties, their children, and the
+  server's administration (users, hosts, domains, brands, OAuth clients,
+  identity providers, proxies). `resource_call` runs their actions, such as
+  verifying a domain, calling an endpoint or testing an alarm rule.
+- Data and files: `bucket_data` (list reads a bucket, create writes
+  samples), `storage_file` (a storage's files; uploads folders of this
+  machine), `device_resource` (a connected device's resources: list, and
+  the `call` action); actions `device` `send` and `overview`,
+  `product_profile_api` `call` and `plugin` `call`.
+- `doc` (the guides for agents), `profile` (the configured servers) and the
+  `dashboard` actions `init`, `dev` and `publish`. `dev` gives an agent the
+  dev link above: with browser tools it opens the app, reads its console
+  and iterates, then publishes it once.
+
+`resource_describe` lists the types with their ids and examples; with a
+type it shows its fields, filter, actions, the permission each operation
+needs and ready-to-send calls, read from the server's own API description.
+Actions that change a lot at once (`replace_all`, a host's settings or
+restart, removing a plugin) answer a plan and run with `confirm: true`.
 Every tool takes an optional `profile`, and most an optional `user`.
+`thinger mcp --read-only` (or `THINGER_MCP_READ_ONLY=1`) serves only what
+reads: describe, list, get and the actions that change nothing.
 
 ## Shared core
 

package/lib/identity.js

@@ -29,9 +29,11 @@ export const thingerIdentity = {
 /** 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 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.
+- Everything is a resource type behind eight tools: thinger_resource_list / _get / _create / _update / _delete / _clone, and thinger_resource_call for actions. Start with thinger_resource_describe without arguments: it lists the types with their ids, operations and actions and explains the platform's concepts (which data source fits each need, recipes). Each type's ids, filter, bodies, actions and ready-to-send examples are in thinger_resource_describe with that type: read it before the first call on a type.
+- A record is located by \`ids\`, one key per level: {"device": "d1"}, {"device": "d1", "property": "setpoint"}, {"product": "p1", "resource": "temp"}. The records the tools answer carry their ids: pass them back as they are.
 - 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 web apps built on the dashboard SDK, the npm package @thinger-io/dashboard-sdk (reference: thinger_resource_describe type "dashboard", or thinger_doc_read id "dashboard-sdk"). Start them with thinger_dashboard_init (a TypeScript project from a template of the SDK), develop them on their own dev server with thinger_dashboard_dev (start the dev server first; the link opens the local app against the server with a temporary token: open it with browser tools to see it and read its console), then build and publish the build folder once with thinger_dashboard_publish.
-- 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.`;
+- Data and files are types too: a bucket's time series is "bucket_data" (list reads it, create writes samples), a storage's files "storage_file". Device resources (the API a connected device's firmware exposes) are "device_resource": list them, and run one with thinger_resource_call action "call".
+- Guides: thinger_resource_list type "doc", then thinger_resource_get type "doc" with ids {"doc": <id>} (concepts, product-code, server-admin, dashboard-sdk…). Read the relevant one before building something new.
+- Custom dashboards are web apps on the dashboard SDK, the npm package @thinger-io/dashboard-sdk (reference: thinger_resource_describe type "dashboard", or the guide "dashboard-sdk"). thinger_resource_call on type "dashboard": action "init" starts one (a TypeScript project from a template of the SDK), "dev" develops it on its own dev server (start the dev server first; the link opens the local app against the server with a temporary token: open it with browser tools to see it and read its console), and "publish" uploads the build folder once it works.
+- Every tool takes an optional \`profile\` (another configured server, see thinger_resource_list type "profile") and most take \`user\` (another account, admin only).
+- Deletes and most actions act immediately: confirm with the user before deleting, overwriting, or running an action that changes, removes or notifies. Actions that change a lot at once (replace_all, a host's settings or restart, removing a plugin) answer a plan first: show it to the user and repeat the call with confirm: true only if they agree.`;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinger-io/cli",
-    "version": "0.3.0",
+    "version": "0.5.0",
     "description": "CLI for Thinger.io servers — devices, products, buckets, dashboard apps — with an MCP server for AI clients",
     "main": "bin/thinger.js",
     "bin": {
@@ -38,7 +38,7 @@
     "author": "Thinger.io",
     "license": "MIT",
     "dependencies": {
-        "@thinger-io/cli-core": "^0.4.0"
+        "@thinger-io/cli-core": "^0.5.0"
     },
     "type": "module",
     "engines": {