CLI Dev Tools

The taladb CLI lets you inspect, export, and manage TalaDB database files from the terminal — useful for debugging, data migration, and CI pipelines.

Installation

Download the pre-built binary for your platform from the GitHub Releases page.

Linux

# Download and extract (replace VERSION with the latest release, e.g. v0.1.1)
curl -L https://github.com/thinkgrid-labs/taladb/releases/download/VERSION/taladb-linux-x86_64-VERSION.tar.gz \
  | tar -xz
sudo mv taladb /usr/local/bin/
taladb --version

macOS

curl -L https://github.com/thinkgrid-labs/taladb/releases/download/VERSION/taladb-macos-aarch64-VERSION.tar.gz \
  | tar -xz
sudo mv taladb /usr/local/bin/
taladb --version

Windows

# Download taladb-windows-x86_64-VERSION.zip from the releases page,
# extract it, and add the folder to your PATH.
taladb --version

Commands

inspect — database overview

Print all collections, their document counts, and any vector indexes defined on them.

taladb inspect ./myapp.db

TalaDB Inspector
────────────────
File: myapp.db

Collections (3):
  articles  (1 247 documents)
    Indexes:     category, locale, publishedAt
    Vector indexes:  embedding (384-dim, cosine)
  sessions  (8 documents)
  users     (56 documents)
    Indexes:     email, age

Vector indexes are shown under the collection they belong to, with their configured dimensions and similarity metric.

---

collections — list collection names

Print one collection name per line (useful for scripting).

taladb collections ./myapp.db

---

count — count documents

taladb count ./myapp.db users
# 56

---

export — dump a collection

Export all documents in a collection to JSON, NDJSON, or CSV.

# Pretty-printed JSON array (default) — prints to stdout
taladb export ./myapp.db users

# Write to a file
taladb export ./myapp.db users --out users.json

# Newline-delimited JSON (one document per line)
taladb export ./myapp.db users --fmt ndjson --out users.ndjson

# CSV (flat fields only)
taladb export ./myapp.db users --fmt csv --out users.csv

Flags

Flag	Short	Default	Description
--fmt	-f	json	Output format: json, ndjson, csv
--out	-o	stdout	Output file path

Embedding fields are exported as regular JSON arrays of numbers — no special handling needed. A document with an embedding field exports exactly as stored:

{
  "_id": "01HWZZQ0000000000000000000",
  "title": "How to reset your password",
  "embedding": [0.023, -0.141, 0.887, "...383 more values..."]
}

This means export + import round-trips preserve embedding data faithfully. The vector index itself is not exported — only the raw field values are. After importing into a new database, call createVectorIndex in your application startup to rebuild the index from the stored embedding fields.

---

import — bulk insert from JSON / NDJSON

Import documents from a JSON array file or NDJSON file. New ULIDs are assigned — any _id fields in the source are ignored.

# From a JSON array
taladb import ./myapp.db users users.json

# From NDJSON
taladb import ./myapp.db users users.ndjson

The database file is created if it does not exist.

Importing documents with embeddings: If your exported documents contain numeric array fields (e.g. embedding), those values are inserted as-is. The vector index is not automatically created — call createVectorIndex in your application after import to make the field searchable:

// After taladb import ./dev.db articles articles.ndjson
const db = await openDB('./dev.db')
await db.collection('articles').createVectorIndex('embedding', { dimensions: 384 })
// Backfill runs automatically — all imported docs with a valid 'embedding' field are indexed

---

drop — clear a collection

Delete all documents in a collection. Indexes defined on the collection are preserved.

taladb drop ./myapp.db sessions
# Deleted 8 documents from 'sessions'

---

Common workflows

Back up a collection before a migration:

taladb export ./prod.db users --out users-backup.json

Seed a local dev database from production export:

taladb import ./dev.db users users-backup.json

Check document counts in CI:

COUNT=$(taladb count ./test.db results)
if [ "$COUNT" -lt 1 ]; then
  echo "No results written — test failed"
  exit 1
fi

Seed a vector collection from an exported dataset:

Export from one database, import into another, then rebuild the vector index at app startup:

# 1. Export from production (embeddings included as plain JSON arrays)
taladb export ./prod.db articles --fmt ndjson --out articles.ndjson

# 2. Import into local dev database
taladb import ./dev.db articles articles.ndjson

# 3. In your app startup — createVectorIndex backfills all imported docs automatically

const db = await openDB('./dev.db')
const articles = db.collection('articles')
await articles.createVectorIndex('embedding', { dimensions: 384 })

Verify vector data is present after import:

# Count should match what was exported
taladb count ./dev.db articles

# Inspect to confirm the vector index was created by the app
taladb inspect ./dev.db
# articles  (1247 documents)
#   Vector indexes:  embedding (384-dim, cosine)

Vector CLI commands (roadmap)

The following commands are planned for a future release and are not yet available:

Command	Description
taladb vector-indexes ./myapp.db	List all vector indexes across all collections
taladb find-nearest ./myapp.db <collection> <field> <vector-json> --top 5	Run a similarity query from the terminal
taladb drop-vector-index ./myapp.db <collection> <field>	Remove a vector index

Track progress on the GitHub issues page.