@thinremote/thinr-cli 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.3.0] - 2026-09-13
+
+### Added
+
+- `thinr login` — re-authenticate the current profile in place, without
+  deleting and recreating it. Renews an expired session in one step and
+  defaults the server prompt to the profile's existing server.
+
+### Changed
+
+- Session-expiry errors now point to the working command: "Session
+  expired. Run `thinr login` to sign in again." (previously suggested
+  `thinr`, which opens the dashboard instead of re-authenticating).
+- More robust token refresh for WebSocket sessions: the interactive
+  console and streaming `exec` now refresh an expired access token
+  before the handshake and retry once on a 401, matching the
+  refresh-on-401 behaviour of HTTP calls.
+
 ## [1.2.0] - 2026-06-10
 
 ### Added

package/README.md

@@ -12,8 +12,8 @@ Two operating modes:
 
 - **CLI** — interactive or scripted device management from a shell.
 - **MCP server** — a stdio [Model Context Protocol][mcp] server that
-  exposes the same operations as typed tools for AI clients like
-  Claude Code.
+  exposes the same operations as 80+ typed tools for AI clients like
+  Claude Code, Claude Desktop and Cursor.
 
 Both modes share the same auth, profiles, and device API layer, so
 you configure the tool once and use it in whichever mode fits the
@@ -39,6 +39,7 @@ task at hand.
     - [Authoring playbooks from natural language](#authoring-playbooks-from-natural-language)
     - [Per-call controls](#per-call-controls)
     - [Integrating with Claude Code](#integrating-with-claude-code)
+    - [Integrating with Claude Desktop, Cursor and other MCP hosts](#integrating-with-claude-desktop-cursor-and-other-mcp-hosts)
 - [Profiles and multi-account use](#profiles-and-multi-account-use)
 - [Development](#development)
 - [License](#license)
@@ -428,44 +429,53 @@ Other profiles are left untouched.
 
 ## Part 2 — MCP server
 
-`thinr` ships an [MCP][mcp] server that exposes the CLI's device
-operations as a set of typed tools. AI clients (Claude Code, Claude
-Desktop, and any other MCP-compatible host) can then list devices,
-run shell commands, read/write files, call resources, and manage
-products through the same API the CLI uses — with stable schemas and
-a consistent error contract.
+`thinr` ships an [MCP][mcp] server that exposes the CLI's device and
+fleet operations as a set of 80+ typed tools. AI clients (Claude Code,
+Claude Desktop, Cursor, and any other MCP-compatible host) can list
+devices, run shell commands, read/write files, call resources, manage
+products, author and roll out playbooks, triage alarms and rotate
+access tokens through the same API the CLI uses — with stable schemas
+and a consistent error contract.
 
 ### Starting the server
 
 ```bash
-thinr mcp [-d, --device <deviceId>]
+thinr mcp
 ```
 
-The server speaks [MCP over stdio][mcp-stdio]. `-d/--device` sets a
-default device that tools can omit in each call; `--user` can be
-passed through (via the global flag) to impersonate another account.
+The server speaks [MCP over stdio][mcp-stdio]. Every tool call carries
+its own `device`, `user` and `profile` arguments, so a single running
+server handles any device of any configured environment without a
+restart.
 
 [mcp-stdio]: https://modelcontextprotocol.io/specification/server/transport#stdio
 
 ### Tool catalog
 
-Grouped by capability. Every tool accepts optional `device`, `user`,
-and `profile` arguments, so a single session can target any
-device/account/environment without restart.
-
-| Area                  | Tools                                                                                                                                                                                        |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Discovery             | `thinr_devices` (with optional `query` for regex filtering), `thinr_device_info`, `thinr_profiles`                                                                                           |
-| Shell                 | `thinr_exec` (buffered), with streaming stdout/stderr                                                                                                                                        |
-| Filesystem            | `thinr_read`, `thinr_write`, `thinr_push`, `thinr_pull`, `thinr_ls`, `thinr_mkdir`, `thinr_rm`, `thinr_mv`                                                                                   |
-| Resources             | `thinr_resource_list` (with `in`/`out` schemas), `thinr_resource_call`                                                                                                                       |
-| Properties            | `thinr_property_get`, `thinr_property_set`                                                                                                                                                   |
-| Scripts (device)      | `thinr_script_list`, `thinr_script_write`, `thinr_script_delete`                                                                                                                             |
-| Monitoring and update | `thinr_monitoring`, `thinr_bucket_read`, `thinr_update`                                                                                                                                      |
-| Products              | `thinr_products`, `thinr_product_delete`, `thinr_device_set_product`, `thinr_product_exec`, `thinr_product_write`                                                                            |
-| Product scripts       | `thinr_product_script_list`, `thinr_product_script_read`, `thinr_product_script_write`, `thinr_product_script_delete`                                                                        |
-| Playbooks (authoring) | `thinr_playbook_schema`, `thinr_playbook_validate`, `thinr_playbook_run` (ad-hoc)                                                                                                            |
-| Product playbooks     | `thinr_product_playbook_list`, `thinr_product_playbook_read`, `thinr_product_playbook_write`, `thinr_product_playbook_run` (single device), `thinr_product_playbook_rollout` (fleet), `thinr_product_playbook_delete` |
+Grouped by capability. Every tool accepts optional `device` (when
+relevant), `user` and `profile` arguments, so a single session can
+target any device, account or environment without restart.
+
+| Area                         | Tools                                                                                                                                                                                                                |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Discovery                    | `thinr_devices` (with optional `query` for regex filtering), `thinr_device_info`, `thinr_profiles`                                                                                                                   |
+| Provisioning and lifecycle   | `thinr_agent_install_command`, `thinr_device_set_product`, `thinr_device_delete`                                                                                                                                     |
+| Shell                        | `thinr_exec` (buffered), with streaming stdout/stderr                                                                                                                                                                |
+| Filesystem                   | `thinr_read`, `thinr_write`, `thinr_push`, `thinr_pull`, `thinr_ls`, `thinr_mkdir`, `thinr_rm`, `thinr_mv`                                                                                                           |
+| Resources                    | `thinr_resource_list` (with `in`/`out` schemas), `thinr_resource_call`                                                                                                                                               |
+| Properties (device)          | `thinr_property_get`, `thinr_property_set`                                                                                                                                                                           |
+| Scripts (device)             | `thinr_script_list`, `thinr_script_write`, `thinr_script_delete`                                                                                                                                                     |
+| Monitoring and agent updates | `thinr_monitoring`, `thinr_bucket_read`, `thinr_update`                                                                                                                                                              |
+| Alarms                       | `thinr_alarm_instances`, `thinr_alarm_instance_stats`, `thinr_alarm_instance_get`, `thinr_alarm_instance_update`, `thinr_alarm_instance_delete`, `thinr_alarm_rules`, `thinr_alarm_rule_read/write/delete`           |
+| Access tokens                | User: `thinr_token_list`, `thinr_token_get`, `thinr_token_create`, `thinr_token_update`, `thinr_token_delete`. Device: `thinr_device_token_list`, `thinr_device_token_create`, `thinr_device_token_delete`           |
+| Products                     | `thinr_products`, `thinr_product_create`, `thinr_product_update`, `thinr_product_delete`, `thinr_product_exec`, `thinr_product_write`                                                                                |
+| Product scripts              | `thinr_product_script_list`, `thinr_product_script_read`, `thinr_product_script_write`, `thinr_product_script_delete`                                                                                                |
+| Product properties           | `thinr_product_property_get`, `thinr_product_property_set`, `thinr_product_property_delete`                                                                                                                          |
+| Product profile schema       | `thinr_product_profile_api_{list,get,set,delete}`, `thinr_product_profile_bucket_{list,get,set,delete}`, `thinr_product_profile_property_{list,get,set,delete}`                                                      |
+| Product log sources          | `thinr_product_logs_list`, `thinr_product_logs_add`, `thinr_product_logs_remove`, `thinr_product_logs_presets`, `thinr_product_logs_set_default`                                                                     |
+| Product metrics              | `thinr_product_metric_list`, `thinr_product_metric_set`, `thinr_product_metric_delete`                                                                                                                               |
+| Playbooks (authoring)        | `thinr_playbook_schema`, `thinr_playbook_validate`, `thinr_playbook_run` (ad-hoc)                                                                                                                                    |
+| Product playbooks            | `thinr_product_playbook_list`, `thinr_product_playbook_read`, `thinr_product_playbook_write`, `thinr_product_playbook_run` (single device), `thinr_product_playbook_rollout` (fleet), `thinr_product_playbook_delete` |
 
 Full input/output schemas are published via standard MCP
 `list_tools`; the client will show them when you connect.
@@ -557,8 +567,27 @@ That's it — a single MCP server entry handles every device of the
 active profile. Tool calls pass `device` (and optionally `user` /
 `profile`) per call.
 
-Other MCP hosts follow the same pattern — they just need the command
-`thinr mcp` (optionally with `-d <deviceId>`) over stdio.
+### Integrating with Claude Desktop, Cursor and other MCP hosts
+
+Other MCP hosts use a JSON config file (`claude_desktop_config.json`,
+`.cursor/mcp.json`, etc.). The entry shape is the same on every host:
+
+```json
+{
+    "mcpServers": {
+        "thinr": {
+            "command": "thinr",
+            "args": ["mcp"]
+        }
+    }
+}
+```
+
+The `thinr` binary must be on `PATH` for the host to spawn it —
+`npm install -g @thinremote/thinr-cli` puts it there. If the host
+runs under a shell that doesn't load your global npm bin
+(common on macOS GUI apps), point `command` at the absolute path
+(`which thinr`) instead.
 
 ---
 

package/bin/thinr.js

@@ -6,7 +6,7 @@ import { dirname, resolve } from 'path';
 import { Command } from 'commander';
 import figlet from 'figlet';
 import { accent, info } from '../lib/format.js';
-import { configExists, readConfig, setActiveProfile } from '../lib/config.js';
+import { configExists, getActiveProfile, readConfig, setActiveProfile } from '../lib/config.js';
 import { detectJsonModeFromArgv } from '../lib/output.js';
 
 // Single source of truth for the version: package.json. Avoids the drift
@@ -64,6 +64,25 @@ playbookCommand(program);
 profileCommand(program);
 logoutCommand(program);
 
+program
+    .command('login')
+    .helpGroup('Profile:')
+    .description('Re-authenticate the current profile (renew an expired session)')
+    .action(async () => {
+        try {
+            // Pin the target to the active/default profile by name so the
+            // refreshed credentials overwrite it in place, even when the
+            // profile name differs from the server hostname.
+            const name = getActiveProfile();
+            if (name) setActiveProfile(name);
+            await authenticate();
+            console.log(info('Signed in.'));
+        } catch (error) {
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
 program
     .command('mcp')
     .helpGroup('Integration:')

package/lib/auth.js

@@ -16,6 +16,10 @@ const OAUTH_DEVICE_CODE_TIMEOUT_MS = TIMEOUTS.OAUTH_DEVICE_CODE_MS;
  * @returns {Promise<void>}
  */
 export async function authenticate() {
+    // When re-authenticating an existing profile, default the server prompt
+    // to the one already stored so `thinr login` is a couple of keystrokes.
+    const existing = readConfig();
+
     // Ask for authentication method
     const method = await select({
         message: 'How would you like to authenticate?',
@@ -29,7 +33,7 @@ export async function authenticate() {
     // Ask for server URL
     const server = await input({
         message: 'Enter server URL:',
-        default: 'console.thinr.io',
+        default: existing?.server || 'console.thinr.io',
         validate: (input) => {
             return input ? true : 'Server URL is required';
         },
@@ -152,7 +156,7 @@ export async function refreshToken() {
 async function doRefresh() {
     const config = readConfig();
     if (!config.refresh_token) {
-        const err = new Error('No refresh token available; re-authenticate with `thinr`.');
+        const err = new Error('Session expired. Run `thinr login` to sign in again.');
         err.code = 'unauthorized';
         throw err;
     }
@@ -172,7 +176,7 @@ async function doRefresh() {
             _isRefresh: true,
         });
     } catch (_error) {
-        const err = new Error('Token refresh failed; re-authenticate with `thinr`.');
+        const err = new Error('Session expired. Run `thinr login` to sign in again.');
         err.code = 'unauthorized';
         throw err;
     }
@@ -184,6 +188,37 @@ async function doRefresh() {
     return response.data.access_token;
 }
 
+/**
+ * Milliseconds-since-epoch expiry of a JWT access token, or null when
+ * the token is not a decodable JWT (permanent API tokens have no exp).
+ */
+function jwtExpiryMs(token) {
+    try {
+        const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString());
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Return a currently-valid access token, refreshing first when the
+ * stored one is an expired (or about-to-expire) JWT. HTTP requests
+ * recover from expiry through the api.js response interceptor, but
+ * WebSocket handshakes have no retry layer: callers opening a WS use
+ * this to start from a valid token. Tokens without a decodable `exp`
+ * and profiles without a refresh_token pass through untouched.
+ */
+export async function ensureFreshToken() {
+    const config = readConfig();
+    if (!config?.token || !config.refresh_token) return config?.token ?? null;
+    const expiresAt = jwtExpiryMs(config.token);
+    if (expiresAt === null || expiresAt - Date.now() > TIMEOUTS.TOKEN_EXPIRY_SLACK_MS) {
+        return config.token;
+    }
+    return refreshToken();
+}
+
 /**
  * Delete user token from server
  * @returns {Promise<void>}

package/lib/command-stream.js

@@ -69,8 +69,7 @@ export class CommandStream {
         this.cancelled = true;
         if (
             this.ws &&
-            (this.ws.readyState === WebSocket.OPEN ||
-                this.ws.readyState === WebSocket.CONNECTING)
+            (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)
         ) {
             this.ws.close();
         }
@@ -100,11 +99,14 @@ export class CommandStream {
     _armSafety() {
         const { timeout } = this.opts;
         if (!timeout || timeout <= 0) return;
-        this.safetyTimer = setTimeout(() => {
-            if (this.resolved) return;
-            this.timedOut = true;
-            this._finish();
-        }, timeout * 1000 + TIMEOUTS.EXEC_SAFETY_GRACE_MS);
+        this.safetyTimer = setTimeout(
+            () => {
+                if (this.resolved) return;
+                this.timedOut = true;
+                this._finish();
+            },
+            timeout * 1000 + TIMEOUTS.EXEC_SAFETY_GRACE_MS,
+        );
     }
 
     _disarmSafety() {
@@ -116,6 +118,19 @@ export class CommandStream {
 
     _wireEvents(ws) {
         ws.on('open', () => this._forwardStdin(ws));
+        ws.on('unexpected-response', (req, res) => {
+            // Handshake rejected before the upgrade (401 expired token,
+            // 404 unknown device, ...). Tag the HTTP status so callers
+            // can react to it; execStream() refreshes and retries on 401.
+            req.destroy();
+            if (this.cancelled || this.resolved) return;
+            this._disarmSafety();
+            const err = /** @type {Error & { statusCode: number }} */ (
+                new Error(`Unexpected server response: ${res.statusCode}`)
+            );
+            err.statusCode = res.statusCode;
+            this._reject?.(err);
+        });
         ws.on('error', (err) => {
             if (this.cancelled || this.resolved) return;
             this._disarmSafety();
@@ -176,8 +191,7 @@ export class CommandStream {
         });
         if (
             this.ws &&
-            (this.ws.readyState === WebSocket.OPEN ||
-                this.ws.readyState === WebSocket.CONNECTING)
+            (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)
         ) {
             this.ws.terminate();
         }

package/lib/console.js

@@ -1,5 +1,6 @@
 import WebSocket from 'ws';
 import { requireConfig } from './config.js';
+import { ensureFreshToken } from './auth.js';
 import api from './api.js';
 import { warning, error as errorStyle } from './format.js';
 
@@ -18,10 +19,15 @@ import { warning, error as errorStyle } from './format.js';
 export async function connectToDeviceConsole(deviceId) {
     const config = requireConfig();
 
+    // WS handshakes lack the refresh-on-401 retry that api.js gives
+    // HTTP requests: start from a valid token (no-op for permanent
+    // tokens, which carry no expiry).
+    const token = (await ensureFreshToken()) || config.token;
+
     const sessionId = createUUID();
     const wsUrl = `wss://${config.server}/v3/users/${config.username}/devices/${deviceId}/resources/$terminal/${sessionId}?raw=1`;
     const ws = new WebSocket(wsUrl, {
-        headers: { Authorization: `Bearer ${config.token}` },
+        headers: { Authorization: `Bearer ${token}` },
     });
 
     let terminalRestored = false;

package/lib/constants.js

@@ -12,6 +12,13 @@ export const TIMEOUTS = {
     /** Default axios request timeout for control-plane HTTP calls. */
     API_DEFAULT_MS: 10_000,
 
+    /**
+     * Refresh a JWT access token this close to (or past) its `exp`
+     * before opening a WebSocket. WS handshakes lack the
+     * refresh-on-401 retry that api.js gives HTTP requests.
+     */
+    TOKEN_EXPIRY_SLACK_MS: 30_000,
+
     /** POSTs to device resources (cmd, update, etc.) — mid-weight calls. */
     DEVICE_RESOURCE_CALL_MS: 30_000,
 

package/lib/device-api.js

@@ -2,6 +2,7 @@ import api from './api.js';
 import { requireConfig } from './config.js';
 import { BYTES, TIMEOUTS } from './constants.js';
 import { CommandStream } from './command-stream.js';
+import { ensureFreshToken, refreshToken } from './auth.js';
 import { Readable } from 'node:stream';
 
 // Directory endpoints on the agent expect a trailing slash so it can
@@ -166,7 +167,11 @@ export function createDeviceAPI(deviceId, options = {}) {
         },
 
         // POST /v3/users/{user}/devices/{device}/resources/{resource}
-        async callResource(resource, payload = null, { timeout = TIMEOUTS.DEVICE_RESOURCE_CALL_MS } = {}) {
+        async callResource(
+            resource,
+            payload = null,
+            { timeout = TIMEOUTS.DEVICE_RESOURCE_CALL_MS } = {},
+        ) {
             const url = `${resourcePath}/${resource}`;
             const response = await api.post(url, payload, { timeout });
             return response.data;
@@ -197,23 +202,39 @@ export function createDeviceAPI(deviceId, options = {}) {
          * Preferred path for the CLI: the server detects WS close and stops
          * the device-side stream automatically. Framing, timeout and
          * cancellation live in `CommandStream` (lib/command-stream.js).
+         *
+         * Auth: the WS handshake has no refresh-on-401 interceptor like
+         * HTTP calls do, so the token is refreshed up front when its JWT
+         * is already expired, and a handshake 401 gets one explicit
+         * refresh-and-retry.
          */
-        execStream(cmd, { timeout = 0, onStdout, onStderr, onCancel, stdin } = {}) {
+        async execStream(cmd, { timeout = 0, onStdout, onStderr, onCancel, stdin } = {}) {
             const isLocal = config.server === 'localhost' || config.server === '127.0.0.1';
             const insecure = isLocal || process.env.THINR_INSECURE === '1';
-            return new CommandStream({
-                server: config.server,
-                token: config.token,
-                apiUser,
-                deviceId,
-                insecure,
-                cmd,
-                timeout,
-                onStdout,
-                onStderr,
-                onCancel,
-                stdin,
-            }).run();
+            const run = (token) =>
+                new CommandStream({
+                    server: config.server,
+                    token,
+                    apiUser,
+                    deviceId,
+                    insecure,
+                    cmd,
+                    timeout,
+                    onStdout,
+                    onStderr,
+                    onCancel,
+                    stdin,
+                }).run();
+            try {
+                return await run((await ensureFreshToken()) || config.token);
+            } catch (error) {
+                // A token that decodes as still-valid can be rejected
+                // anyway (revoked, clock skew): mirror the api.js
+                // interceptor and retry the handshake once after an
+                // explicit refresh.
+                if (error?.statusCode !== 401) throw error;
+                return run(await refreshToken());
+            }
         },
     };
 }

package/lib/errors.js

@@ -7,6 +7,18 @@
  * that names the missing entity (e.g. "Device not found: abc").
  */
 export function apiError(error, messages = {}) {
+    // Errors normalized upstream (the tagged 'unauthorized' from a failed
+    // token refresh, inputError, ...) carry a stable string code and no
+    // axios envelope: pass them through so the code survives.
+    if (
+        error &&
+        typeof error.code === 'string' &&
+        !error.isAxiosError &&
+        !error.response &&
+        !error.request
+    ) {
+        return error;
+    }
     if (error && error.response) {
         const status = error.response.status;
         if (status === 404) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinremote/thinr-cli",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "description": "CLI for ThinRemote — remote management for IoT devices, with an MCP server for AI clients",
     "main": "bin/thinr.js",
     "bin": {