DialogueDB Client v2.0.0: CLI, Better Search, Stricter Types

The dialogue-db npm package just hit v2.0.0. This is a major release with three big additions: a full command-line interface, a redesigned search API with proper filtering operators, and tighter validation across the board. If you’re new to DialogueDB, our introductory post covers the core concepts. This post assumes you’re already familiar with the basics.

If you’re on v1.x, there are breaking changes. This post covers what’s new, what changed, and what you need to update.

The CLI

You can now interact with DialogueDB from your terminal without writing any code. The CLI covers the full API surface: dialogues, messages, memories, and search.

Install it (or update) from npm:

npm install -g dialogue-db

Set your API key and you’re ready:

export DIALOGUEDB_API_KEY=your-key

Create a dialogue, add messages, and search across them:

# Create a dialogue
dialogue-db dialogue create --label "support-session" --tags "support,billing"

# Add a message
dialogue-db message add <dialogue-id> \
  --role user \
  --content "How do I upgrade my plan?"

# Search across all messages
dialogue-db search messages "plan upgrade" --limit 5

The CLI also supports batch message insertion from a JSON file, which is useful for importing existing conversation data:

dialogue-db message add-batch <dialogue-id> \
  --file messages.json

Where messages.json contains an array of { role, content } objects.

Every subcommand supports --namespace for multi-tenant setups, and all output is JSON, so you can pipe it into jq or any other tool in your workflow.

# List dialogues and extract IDs
dialogue-db dialogue list --limit 10 | jq '.[].id'

# Search with tag filtering
dialogue-db search memories "user preferences" \
  --tags "onboarding,settings"

Full command reference: dialogue-db --help, or dialogue-db <command> --help for any subcommand.

Search API overhaul

The search API in v2.0.0 replaces the old date-field filtering with a proper operator-based system. This applies to both the SDK methods and the CLI.

Tag operators

Tags now support $in, $all, and $nin operators instead of just simple arrays:

import { searchMessages } from "dialogue-db";

const results = await searchMessages("billing question", {
  tags: {
    $all: ["support", "billing"],
    $nin: ["resolved"],
  },
});

Passing a plain string[] still works and is treated as $in semantics, so existing code that uses simple tag arrays doesn’t break.

Metadata operators

Metadata filtering now supports comparison and set operators: $eq, $ne, $in, $nin, $gt, $gte, $lt, $lte.

const results = await searchDialogues("onboarding flow", {
  metadata: {
    priority: { $gte: 3 },
    channel: { $in: ["web", "mobile"] },
    resolved: { $ne: true },
  },
});

You can still pass a bare value for simple equality, so { channel: "web" } works as before.

Date filters

The old decomposed date fields (createdYear, createdMonth, createdDay, etc.) are gone. If you pass them, the SDK throws an error with a migration hint pointing you to the new filter option.

The replacement is cleaner. Pass ISO 8601 strings or natural-language phrases:

const results = await searchMessages("deployment issues", {
  filter: {
    created: { gte: "2026-03-01", lt: "2026-04-01" },
  },
});

// Natural language works too
const recent = await searchMemories("user preferences", {
  filter: {
    modified: "last week",
  },
  timezone: "America/New_York",
});

The timezone option controls how natural-language phrases resolve. It defaults to UTC.

Ordering

Results can now be sorted by relevance (default), created, or modified:

const results = await searchMessages("error handling", {
  orderBy: "created",
  order: "desc",
});

Dialogue search with evidence

When you search dialogues, each result now includes a matches array with the most relevant messages that contributed to the match. This gives you context about why a dialogue was returned without making a second API call.

const { results } = await searchDialogues("password reset");

for (const result of results) {
  console.log(result.item.id, result.relevance);
  for (const match of result.matches ?? []) {
    console.log("  evidence:", match.item.content);
  }
}

Stricter validation

Validators in v2.0.0 are colocated with their resources instead of living in a shared file. This doesn’t affect your code directly, but the validation itself is stricter.

The SDK now validates inputs before they hit the network. If you pass an invalid operator, a non-string tag, or a malformed metadata filter, you get a DialogueDBError with a specific code and field path instead of a generic 400 from the server. This makes debugging faster because you see the problem immediately in your local stack trace.

// This throws locally with a clear message:
// "tags.$all must contain only non-empty strings"
await searchMessages("test", {
  tags: { $all: [123] },
});

Migrating from v1.x

The main things to update:

1. Date filters: Replace createdYear/createdMonth/createdDay/createdTimestamp with filter: { created: { gte, lt } }. Same for modified variants. The SDK error messages tell you exactly what to change.

2. Tag filtering: If you were passing tags: ["a", "b"], that still works (treated as $in). No change needed unless you want the new operators.

3. Metadata filtering: Simple equality values still work. The new operators are additive.

4. CLI: This is new, not a migration. Install and use it alongside the SDK, or as a standalone tool for scripting and debugging.

The type system is also tighter. If TypeScript flags something after the upgrade, it’s likely catching a real type mismatch that v1.x was silently accepting.

What’s next

The CLI in this release covers the full API surface, but there’s more to come. If you run into issues or have feature requests, open an issue on the GitHub repo.

To get started with DialogueDB or try the new CLI, check out the quickstart guide and the search API reference.