@thingd/cli

Search thingd objects and events by full-text query. Returns matching items ranked by relevance using Tantivy BM25 with stemming. Use this to find previously stored memories, notes, or events by keyword or phrase. Accepts a query string and optional filter by collection names, metadata key-value pairs, and a result limit. Returns an array of matching objects with relevance scores.

Read one thingd object by collection name and id. Returns the full object if found, or null if not found. Use this to retrieve a specific stored record when you know its exact collection and id. Returns a single object or null.

Create or replace one object-shaped memory record in a collection. The object must have an 'id' field. If an object with the same id already exists in the collection, it is replaced. Use this to store memories, notes, tasks, or any structured data. Returns the stored object with collection, version, and timestamps.

Delete one thingd object by collection name and id. Permanently removes the object from the store. Returns a result indicating whether the deletion was successful. Use this to remove outdated or incorrect records.

Append an event to a named event stream. Events are append-only, ordered records with a 'type' field and arbitrary payload. Use this to record occurrences, state changes, or audit entries. Each event gets an auto-incremented sequence id. Returns the stored event with id, stream, and timestamp.

List events from a thingd stream, optionally filtered by stream name, starting from a specific sequence number, with a configurable limit, or filtered by timestamp. Use this to review recent activity, replay events, or audit changes. Returns an array of events ordered by sequence.

Push a durable job onto a named queue. Jobs have a JSON payload and can include an idempotency key, max retry attempts, and a delay before the job becomes ready. Use this to schedule background work like processing, notifications, or data pipelines. Returns the created job with id, queue, and status.

Claim the next ready job from a queue. The job is leased for a configurable duration (default 30s). If not acked or nacked before the lease expires, it returns to the ready state. Returns the claimed job with payload, or null if no jobs are ready. Use this to process queue work in a worker loop.

Mark one leased queue job as completed. This removes the job from the queue permanently. Call this after successfully processing a claimed job. Returns a result with ok status and the final job status.

Reject a leased queue job for retry or dead-letter routing. If the job has remaining attempts, it goes back to ready (optionally after a delay). If attempts are exhausted, it moves to the dead-letter list. Optionally attach an error message. Returns a result with ok status and the updated job status.

List all jobs in a queue across all states (ready, leased, dead-letter). Use this to inspect queue contents, monitor backlog, or debug stuck jobs. Returns an array of job objects with id, payload, status, attempts, and timestamps.

List dead-letter jobs in a queue. These are jobs that exhausted all retry attempts. Use this to inspect failed work, diagnose errors, or decide whether to retry or discard. Returns an array of dead-letter job objects.

List objects in a collection with optional filtering, sorting, limit, and offset. Returns an array of objects. Use sortBy.field to sort by id, collection, created_at, updated_at, or version.

Count all objects stored across all collections. Returns a single number representing the total object count. Use this for quick inventory checks or monitoring storage usage.

Count objects in a specific collection. Returns a single number. Uses an indexed query for O(log n) performance.

Count all events across all streams. Returns a single number representing the total event count. Use this to monitor event volume or check stream activity.

Count all active (non-dead) queue jobs across all queues. Includes ready, leased, and delayed jobs. Use this to monitor queue depth and worker load.

Count all dead-letter queue jobs across all queues. These are jobs that failed all retry attempts. Use this to monitor failure rates and decide when to investigate or discard.

List all object collection names in the store. Returns an array of collection name strings. Use this to discover what data is stored before searching or querying.

List all event stream names in the store. Returns an array of stream name strings. Use this to discover available event streams before listing or appending events.

List all queue names in the store. Returns an array of queue name strings. Use this to discover available queues before pushing or claiming jobs.

Create a functional index on a JSON body field for a collection. Subsequent listObjects calls with filter on this field will use the index for O(log n) lookups instead of full table scans. Idempotent — recreating an existing index is a no-op.

Delete a custom functional index.

List all custom functional indexes. Returns an array of [collection, field] pairs.

Create or replace multiple objects in a collection in a single operation. More efficient than calling thing_put repeatedly. Returns the array of stored objects.

Delete multiple objects by ID in a single operation. Returns the count of deleted objects.

Read multiple objects by ID in a single operation. Returns an array of objects (null for missing IDs). More efficient than calling thing_get repeatedly.

Create a directed graph link between two references (e.g., thingd objects, external URLs). You can optionally assign a linkType (e.g., 'parent', 'related_to'), weight, and metadata JSON string.

Delete a graph link by its id. Returns an object with a deleted boolean.

Get a graph link by its id.

Get all links connected to a specific reference. You can filter by direction (Outgoing, Incoming, Both) and linkType.

Count all graph links in the store.

Run aggregate queries on objects in a collection. Supports count, sum, avg, min, max with optional groupBy and filter.

Run time-series aggregation on objects. Buckets objects by hour/day/week/month and applies an aggregate function.

Search objects by vector similarity (cosine similarity). Provide a query vector as an array of floats (e.g. [0.1, 0.2, 0.3]) and optionally set topK and a metadata filter. Returns matching objects ranked by similarity score.

Reflect the schema of one or all collections by sampling stored objects. Returns inferred field names, types, and sample values.

Parse and validate schema.thingd source without changing stored data. Returns canonical schema JSON and a stable SHA-256 hash.

List durable schema migration records and their applied hashes.

Ask a natural language question about your data. Requires NLQ configuration with an LLM endpoint.

Create or update a recurring schedule with a cron expression. Schedules persist across restarts and emit lifecycle events (started, completed, failed, disabled). The handler executes when the cron triggers. Returns the created schedule with nextRunAt.

Create a schedule that runs at a fixed interval (e.g. every 5 minutes). Accepts intervalMs for the delay between runs. Returns the created schedule.

Create a schedule that runs once at a specific ISO timestamp. The schedule auto-disables after execution. Returns the created schedule.

List all registered schedules with their current status, next run time, and run/fail counts. Returns an array of schedule objects.

Get details of a single schedule by ID including its expression, next run, last status, and run/fail counts. Returns null if not found.

Get aggregate statistics for the scheduler: total schedules, enabled, disabled, currently running, and the next scheduled run.

Pause a schedule so it stops triggering. The schedule remains stored and can be resumed later. Returns the updated schedule.

Resume a paused schedule. The next run time is recalculated from the current time. Returns the updated schedule.

Immediately execute a schedule's handler, regardless of its next run time. Useful for testing or manual triggers. The schedule must have a registered handler.

Permanently delete a schedule and its handler. This cannot be undone. Returns whether the schedule was deleted.