thingd-cli 0.1.0 → 0.3.0

package/README.md

@@ -1,50 +1,153 @@
 # thingd-cli
 
-Admin and operator CLI for `thingd`.
+[![npm version](https://badge.fury.io/js/thingd-cli.svg)](https://www.npmjs.com/package/thingd-cli)
 
-This package provides the `thingd` binary. It uses the public
-`thingd` SDK for store access and can connect to a local store or
-a remote sidecar through `THINGD_URL`.
+Admin and operator CLI for [thingd](https://www.npmjs.com/package/thingd).
 
-## Build And Test
+This package provides the `thingd` binary. It uses the public `thingd` SDK for store access and can connect to a local store or a remote sidecar through `THINGD_URL`.
+
+## Installation
+
+Install globally via npm to use the `thingd` command anywhere:
 
 ```bash
-pnpm --filter thingd-cli build
-pnpm --filter thingd-cli test
+npm install -g thingd-cli
 ```
 
-## Usage
+Or run it on the fly using `npx`:
 
 ```bash
-thingd status
-thingd objects put decisions rust-core --text "Use Rust for the core engine."
-thingd objects get decisions rust-core
-thingd events append project:thingd decision.made --text "Picked the CLI shape."
-thingd events list project:thingd
-thingd queues push embed --payload '{"object":"docs/readme"}'
-thingd queues claim embed
+npx thingd-cli
 ```
 
-Remote sidecar mode:
+## Two Modes of Operation
+
+The CLI is designed to support both human operators and automated scripts through two distinct modes:
+
+1. **Interactive Dashboard (TUI)**: Run `thingd` without any arguments to launch a beautiful, interactive terminal UI. Perfect for exploring collections, editing objects, and managing queues manually.
+2. **Non-Interactive CLI**: Run `thingd <command>` for one-off operations. This mode intentionally emits JSON so it is easy to use from shell scripts, CI/CD pipelines, and AI-agent workflows.
+
+---
+
+## 1. Interactive Dashboard (TUI)
 
+To start the interactive dashboard, simply run:
 ```bash
-THINGD_URL=http://127.0.0.1:8757
-THINGD_AUTH_TOKEN=change-me
-thingd status
-thingd tools
+thingd
 ```
 
-Common options:
+### Connection Mode
+Upon launch, you will be prompted to select a connection driver:
+- `Memory`: An ephemeral, in-memory instance (great for quick testing).
+- `Native`: Connects directly to a local SQLite `.db` file (requires a file path).
+- `Cloud`: Connects to a remote ThingD cluster (requires a URL and an optional Bearer Token).
+
+### Keyboard Shortcuts
+Once connected, the TUI provides a dual-pane layout: a navigation sidebar on the left and a detailed viewer/editor on the right.
+
+| Shortcut | Action |
+|----------|--------|
+| `↑` / `↓` (or `k` / `j`) | Navigate the tree vertically |
+| `←` / `→` (or `h` / `l`) | Expand or collapse folders (Collections, Streams, Queues) |
+| `Enter` | Expand node or open a folder |
+| `c` | **Create** a new Object, Event, or push a Queue job |
+| `e` | **Edit** an Object or retry a Queue job |
+| `d` | **Delete** an Object or Ack/Resolve a Queue job |
+| `/` (or `f`) | **Global Semantic Search** across the database |
+| `i` | **Info**: View Connection Info & Cloud Cluster Status |
+| `r` | **Refresh** data from the database |
+| `s` | **Switch** database connections |
+| `q` | **Quit** |
+
+---
+
+## 2. Non-Interactive CLI
+
+For scripts and automation, you can bypass the TUI entirely. 
+
+### Common Options
+You can configure the connection via environment variables or CLI flags:
 
 ```txt
 --url <url>          remote thingd URL. Defaults to THINGD_URL
---auth-token <tok>  remote bearer token. Defaults to THINGD_AUTH_TOKEN
---path <path>       local database path. Defaults to THINGD_PATH or :memory:
---driver <driver>   memory, native, or remote
---pretty            pretty-print JSON output
---limit <n>         result limit for search and list commands
+--auth-token <tok>   remote bearer token. Defaults to THINGD_AUTH_TOKEN
+--path <path>        local database path. Defaults to THINGD_PATH or :memory:
+--driver <driver>    memory, native, or cloud
+--pretty             pretty-print JSON output
+--limit <n>          result limit for search and list commands
+```
+
+### Claude Desktop & MCP Integration
+
+The `thingd` CLI has a built-in `mcp` subcommand that exposes an MCP server over `stdio`. This allows Claude Desktop to securely connect to your `thingd` database.
+
+**Connecting to a Local Database:**
+To let Claude read and write to a local `thingd.db` file, add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "thingd-local": {
+      "command": "thingd",
+      "args": ["mcp", "--path", "/absolute/path/to/thingd.db", "--driver", "native"]
+    }
+  }
+}
+```
+
+**Bridging Claude to the Cloud:**
+Claude Desktop natively only supports local `stdio` servers. However, `thingd mcp` can act as a bridge! If you provide a `--url`, the CLI will launch locally but seamlessly proxy all of Claude's requests to your remote cluster:
+
+```json
+{
+  "mcpServers": {
+    "thingd-cloud": {
+      "command": "thingd",
+      "args": ["mcp", "--url", "https://your-thingd-cloud.com/mcp", "--auth-token", "your-secret-token"]
+    }
+  }
+}
+```
+
+### Command Reference
+
+**Metrics & Discovery**
+```bash
+thingd metrics                # Get total counts (objects, events, activeJobs, deadJobs)
+thingd status                 # Check cluster health (requires --url)
+thingd tools                  # List available MCP tools (requires --url)
+thingd collections list       # List all collection names
+thingd streams list           # List all stream names
+thingd queues list-all        # List all queue names
+```
+
+**Search**
+```bash
+thingd search "my query" [--collection <name>] [--limit <n>]
+```
+
+**Objects**
+```bash
+thingd objects put decisions rust-core --text "Use Rust for the core engine."
+thingd objects put decisions rust-core --data '{"status":"active"}'
+thingd objects get decisions rust-core
+thingd objects delete decisions rust-core
+```
+
+**Events**
+```bash
+thingd events append project:thingd decision.made --text "Picked the CLI shape."
+thingd events list project:thingd
+```
+
+**Queues**
+```bash
+thingd queues push embed --payload '{"object":"docs/readme"}'
+thingd queues claim embed
+thingd queues ack embed <jobId>
+thingd queues nack embed <jobId> --error "failed to fetch" --delay-ms 5000
+thingd queues list embed
+thingd queues dead embed
 ```
 
-The first CLI version intentionally emits JSON so it is easy to use from shell
-scripts, tests, and AI-agent workflows.
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { ThingD, type ThingDDriver } from "thingd";
 type CliEnv = Record<string, string | undefined>;
 type WritableLike = {
     write(chunk: string): void;
@@ -8,6 +9,26 @@ export type RunCliOptions = {
     stdout?: WritableLike;
     stderr?: WritableLike;
 };
+type ParsedArgs = {
+    tokens: string[];
+    flags: Map<string, string[]>;
+    booleans: Set<string>;
+};
+export type CliContext = {
+    parsed: ParsedArgs;
+    env: CliEnv;
+    stdout: WritableLike;
+    stderr: WritableLike;
+    pretty: boolean;
+};
+export type ConnectionOptions = {
+    path: string;
+    driver?: ThingDDriver;
+    authToken?: string;
+    cloud: boolean;
+};
 export declare function runCli(args?: string[], options?: RunCliOptions): Promise<number>;
+export declare function withDb(context: CliContext, callback: (db: ThingD) => Promise<void>): Promise<void>;
+export declare function resolveConnection(context: CliContext): ConnectionOptions;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAgBA,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjD,KAAK,YAAY,GAAG;IAClB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAwDF,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA4BjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAKA,OAAO,EAOL,MAAM,EACN,KAAK,YAAY,EAClB,MAAM,QAAQ,CAAC;AAIhB,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjD,KAAK,YAAY,GAAG;IAClB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAuCF,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAiCjB;AAmUD,wBAAsB,MAAM,CAC1B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAcf;AA4BD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,iBAAiB,CAYxE"}

package/dist/index.js

@@ -3,6 +3,8 @@ import { pathToFileURL } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { ThingD, } from "thingd";
+import { runInteractiveCli } from "./interactive.js";
+import { runMcp } from "./mcp.js";
 const HELP_TEXT = `thingd
 
 Admin and operator CLI for thingd.
@@ -17,18 +19,22 @@ Usage:
   thingd objects delete <collection> <id>
   thingd events append <stream> <type> [--text <text>] [--data '{"field":"value"}']
   thingd events list [stream] [--limit <n>]
+  thingd collections list
+  thingd streams list
+  thingd queues list-all
   thingd queues push <queue> --payload '{"key":"value"}'
   thingd queues claim <queue> [--lease-ms <ms>]
   thingd queues ack <queue> <jobId>
   thingd queues nack <queue> <jobId> [--error <message>] [--delay-ms <ms>]
   thingd queues list <queue> [--limit <n>]
   thingd queues dead <queue> [--limit <n>]
+  thingd metrics
 
 Options:
   --url <url>          remote thingd URL. Defaults to THINGD_URL
   --auth-token <tok>  remote bearer token. Defaults to THINGD_AUTH_TOKEN
   --path <path>       local database path. Defaults to THINGD_PATH or :memory:
-  --driver <driver>   memory, native, or remote
+  --driver <driver>   memory, native, or cloud
   --pretty            pretty-print JSON output
   --limit <n>         result limit for search and list commands
   -h, --help          show help
@@ -44,10 +50,14 @@ export async function runCli(args = process.argv.slice(2), options = {}) {
         pretty: hasFlag(parsed, "pretty"),
     };
     try {
-        if (hasFlag(parsed, "help") || hasFlag(parsed, "h") || parsed.tokens.length === 0) {
+        if (hasFlag(parsed, "help") || hasFlag(parsed, "h")) {
             writeText(context.stdout, HELP_TEXT);
             return 0;
         }
+        if (parsed.tokens.length === 0) {
+            await runInteractiveCli();
+            return 0;
+        }
         await runCommand(context);
         return 0;
     }
@@ -72,6 +82,10 @@ async function runCommand(context) {
         await runSearch(context);
         return;
     }
+    if (command === "mcp") {
+        await runMcp(context);
+        return;
+    }
     if (command === "objects") {
         await runObjects(context);
         return;
@@ -80,15 +94,27 @@ async function runCommand(context) {
         await runEvents(context);
         return;
     }
+    if (command === "collections") {
+        await runCollections(context);
+        return;
+    }
+    if (command === "streams") {
+        await runStreams(context);
+        return;
+    }
     if (command === "queues") {
         await runQueues(context);
         return;
     }
+    if (command === "metrics") {
+        await runMetrics(context);
+        return;
+    }
     throw new Error(`Unknown command: ${command}`);
 }
 async function runStatus(context) {
     const connection = resolveConnection(context);
-    if (!connection.remote) {
+    if (!connection.cloud) {
         writeJson(context.stdout, {
             mode: "local",
             driver: connection.driver ?? "memory",
@@ -96,28 +122,28 @@ async function runStatus(context) {
         }, context.pretty);
         return;
     }
-    const baseUrl = resolveRemoteBaseUrl(connection.path);
+    const baseUrl = resolveCloudBaseUrl(connection.path);
     const [health, cluster] = await Promise.all([
         fetchJson(new URL("/healthz", baseUrl), connection.authToken),
         fetchJson(new URL("/cluster/status", baseUrl), connection.authToken),
     ]);
     writeJson(context.stdout, {
-        mode: "remote",
-        url: resolveRemoteMcpUrl(connection.path),
+        mode: "cloud",
+        url: resolveCloudMcpUrl(connection.path),
         health,
         cluster,
     }, context.pretty);
 }
 async function runTools(context) {
     const connection = resolveConnection(context);
-    if (!connection.remote) {
+    if (!connection.cloud) {
         throw new Error("tools requires --url or THINGD_URL because tools are exposed by the MCP runtime");
     }
     const client = new Client({
         name: "thingd-cli",
         version: "0.1.0",
     });
-    const transport = new StreamableHTTPClientTransport(new URL(resolveRemoteMcpUrl(connection.path)), {
+    const transport = new StreamableHTTPClientTransport(new URL(resolveCloudMcpUrl(connection.path)), {
         requestInit: connection.authToken
             ? {
                 headers: {
@@ -194,10 +220,50 @@ async function runEvents(context) {
         throw new Error(`Unknown events action: ${action}`);
     });
 }
+async function runCollections(context) {
+    const action = requiredToken(context.parsed, 1, "collections action");
+    await withDb(context, async (db) => {
+        if (action === "list") {
+            writeJson(context.stdout, await db.listCollections(), context.pretty);
+            return;
+        }
+        throw new Error(`Unknown collections action: ${action}`);
+    });
+}
+async function runStreams(context) {
+    const action = requiredToken(context.parsed, 1, "streams action");
+    await withDb(context, async (db) => {
+        if (action === "list") {
+            writeJson(context.stdout, await db.listStreams(), context.pretty);
+            return;
+        }
+        throw new Error(`Unknown streams action: ${action}`);
+    });
+}
+async function runMetrics(context) {
+    await withDb(context, async (db) => {
+        const [objects, events, activeJobs, deadJobs] = await Promise.all([
+            db.countObjects(),
+            db.countEvents(),
+            db.countActiveJobs(),
+            db.countDeadJobs(),
+        ]);
+        writeJson(context.stdout, {
+            objects,
+            events,
+            activeJobs,
+            deadJobs,
+        }, context.pretty);
+    });
+}
 async function runQueues(context) {
     const action = requiredToken(context.parsed, 1, "queues action");
-    const queueName = requiredToken(context.parsed, 2, "queue");
     await withDb(context, async (db) => {
+        if (action === "list-all") {
+            writeJson(context.stdout, await db.listQueues(), context.pretty);
+            return;
+        }
+        const queueName = requiredToken(context.parsed, 2, "queue");
         const queue = db.queue(queueName);
         if (action === "push") {
             const payload = parseJsonRecord(requiredFlag(context.parsed, "payload"));
@@ -239,11 +305,11 @@ async function runQueues(context) {
         throw new Error(`Unknown queues action: ${action}`);
     });
 }
-async function withDb(context, callback) {
+export async function withDb(context, callback) {
     const connection = resolveConnection(context);
     const db = await ThingD.open({
         path: connection.path,
-        url: connection.remote ? connection.path : undefined,
+        url: connection.cloud ? connection.path : undefined,
         driver: connection.driver,
         authToken: connection.authToken,
     });
@@ -275,16 +341,16 @@ function buildMemoryEvent(parsed, type) {
         ...(text === undefined ? {} : { text }),
     };
 }
-function resolveConnection(context) {
+export function resolveConnection(context) {
     const url = stringFlag(context.parsed, "url") ?? context.env.THINGD_URL;
     const path = url ?? stringFlag(context.parsed, "path") ?? context.env.THINGD_PATH ?? ":memory:";
-    const remote = isRemotePath(path);
+    const cloud = isCloudPath(path);
     const driver = parseDriver(stringFlag(context.parsed, "driver") ?? context.env.THINGD_DRIVER);
     return {
         path,
-        driver: driver ?? (remote ? "remote" : undefined),
+        driver: driver ?? (cloud ? "cloud" : undefined),
         authToken: stringFlag(context.parsed, "auth-token") ?? context.env.THINGD_AUTH_TOKEN,
-        remote,
+        cloud,
     };
 }
 function parseArgs(args) {
@@ -366,7 +432,7 @@ function parseDriver(value) {
     if (value === undefined) {
         return undefined;
     }
-    if (value === "memory" || value === "native" || value === "remote") {
+    if (value === "memory" || value === "native" || value === "cloud") {
         return value;
     }
     throw new Error(`Unsupported driver: ${value}`);
@@ -384,24 +450,24 @@ function compactOptions(options) {
 function limitItems(items, limit) {
     return limit === undefined ? items : items.slice(0, limit);
 }
-function isRemotePath(path) {
+function isCloudPath(path) {
     return path.startsWith("http://") || path.startsWith("https://") || path.startsWith("thingd://");
 }
-function resolveRemoteMcpUrl(value) {
-    const url = new URL(normalizeRemoteUrl(value));
+function resolveCloudMcpUrl(value) {
+    const url = new URL(normalizeCloudUrl(value));
     if (url.pathname === "" || url.pathname === "/") {
         url.pathname = "/mcp";
     }
     return url.toString();
 }
-function resolveRemoteBaseUrl(value) {
-    const url = new URL(normalizeRemoteUrl(value));
+function resolveCloudBaseUrl(value) {
+    const url = new URL(normalizeCloudUrl(value));
     if (url.pathname === "/mcp") {
         url.pathname = "/";
     }
     return url.toString();
 }
-function normalizeRemoteUrl(value) {
+function normalizeCloudUrl(value) {
     return value.startsWith("thingd://") ? `http://${value.slice("thingd://".length)}` : value;
 }
 async function fetchJson(url, authToken) {

package/dist/interactive.d.ts

@@ -0,0 +1,2 @@
+export declare function runInteractiveCli(): Promise<void>;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/interactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../src/interactive.ts"],"names":[],"mappings":"AA2jDA,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4BvD"}