docs / guides

For agents

botdb's agent skill. Agents fetch it raw from /skill.md, print it withbotdb skill, or get it installed with botdb skill install.

name: botdb
description: Persistent, synced SQL databases for agents. Use botdb whenever you need to remember structured information across sessions or machines (lists, logs, preferences, trackers like "movies I watched"), instead of JSON files or memory notes. Data is local SQLite, works offline, syncs end-to-end encrypted between devices, and is backed up automatically.

botdb

botdb gives you real SQL tables that persist across sessions, survive machine changes and sync between agents and devices. Every device keeps a full local copy, so reads and writes are instant and work offline. Changes sync end-to-end encrypted through botdb cloud (the hosted relay, the default), a self-hosted relay or a shared folder.

Use it instead of JSON files or memory notes for anything with structure: watchlists, reading logs, contacts, habits, task queues, research notes, preferences.

Setup

If botdb isn’t installed (botdb --version fails), install it (macOS arm64 and Linux):

curl -fsSL https://botdb.dev/install.sh | sh   # installs to ~/.local/bin

If botdb ls fails with not_logged_in, set up a vault. Either ask the user to run botdb login in a terminal, or, if they asked you to set botdb up, run it yourself:

botdb login     # prints {"vault","phrase","remotes"}: a 24-word recovery phrase and a free botdb cloud account

The phrase is the only way to restore the user’s databases on another machine, and anyone who has it can read them. Show it to the user once, tell them to write it down and run botdb vault verify, and never save it in files, notes, memory or later messages.

Quick start

botdb ls                                  # list databases (JSON when piped)
botdb create movies                       # new database
botdb use movies                          # make it the default for -d
botdb sql "CREATE TABLE watched (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  title TEXT NOT NULL DEFAULT '',
  rating INTEGER,
  watched_at TEXT DEFAULT (datetime('now'))
)"
botdb sql "INSERT INTO watched (title, rating) VALUES (?, ?)" -p "Dune: Part Two" -p 5
botdb sql "SELECT title, rating FROM watched ORDER BY watched_at DESC LIMIT 10"
botdb schema                              # tables, columns and row counts

Never print or store the recovery phrase or invites unless the user asks.

Output

Output is JSON when stdout is not a terminal: a SELECT prints an array of row objects, writes print {"ok": true, "changes": N}.
Errors print {"error": {"code", "message", "hint"}} to stderr with a non-zero exit code. Read the hint: it says how to fix the statement.
Force a format with -F json|table|csv.
Use -d <db> to pick a database (or BOTDB_DB). With one database, it’s picked automatically.

SQL

botdb speaks SQLite’s dialect. Everything you’d expect in a SELECT works: joins, CTEs, window functions, JSON functions, aggregates. Writes: INSERT, UPDATE, DELETE, INSERT ... ON CONFLICT DO UPDATE, REPLACE. A multi-statement script runs atomically (all or nothing). Pass values with -p (positional ?) or --params '{"name": "x"}' (named :name), never by string concatenation.

Schema changes work like normal SQL: CREATE TABLE, ALTER TABLE ... ADD/DROP/RENAME COLUMN, ALTER TABLE ... RENAME TO, DROP TABLE, CREATE INDEX, CREATE VIEW. They sync to every device.

Rules for synced tables

Synced tables must merge safely when devices edit offline, so a few things are rejected with a hint:

Rule	Do this instead
Every table needs an explicit `PRIMARY KEY`	`id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16))))`
No `INTEGER PRIMARY KEY` (auto-increment ids collide across devices)	random text ids as above, or `INT PRIMARY KEY` if you always supply the id
`NOT NULL` columns need a `DEFAULT`	`title TEXT NOT NULL DEFAULT ''`
No `UNIQUE` constraints or unique indexes	make the unique value the primary key, or check before inserting
No `CHECK` constraints, generated columns or triggers	validate in your own logic

Foreign keys can be declared but aren’t enforced. Tables whose name starts with _ are local-only: they never sync and have no restrictions (useful for scratch data or caches).

Conflicts

If two devices change the same row offline, each column keeps the most recent write. A delete wins over concurrent edits; inserting the row again brings it back. Prefer natural keys (e.g. a movie’s IMDb id) when the same thing might be added from two places, so the rows merge instead of duplicating.

History and undo

botdb history watched --limit 20          # recent changes to a table
botdb history watched --pk abc123         # changes to one row
botdb revert --at "2h"                    # restore the database as of 2 hours ago
botdb revert --at 2026-10-01 --table watched

Reverts are new changes, so they sync too. Times accept 30m, 2h, 3d, 1w, dates, or RFC 3339.

Sync happens automatically after writes and before reads. botdb sync forces it; botdb status shows pending changes and the last sync.
Databases sync through botdb cloud by default (free during beta: 20 databases, 50 MB each). botdb cloud shows the plan and usage. cloud works anywhere a remote is expected: botdb remote add cloud -d movies.
botdb invite movies prints an invite (bdb1_...) for another device or agent; --read-only stops them from writing. On the other side: botdb join bdb1_.... Invites are secrets.
In containers or CI, set BOTDB_INVITE=bdb1_... and botdb joins that database automatically.
Backups: every device is a full copy, remotes hold encrypted copies, and local encrypted snapshots are taken daily. botdb cloud also keeps a daily encrypted backup of each database for up to a month: botdb backup ls --remote, botdb backup restore --remote -d movies --at 3d (then run the botdb revert it prints). botdb backup create writes a single encrypted archive; botdb export -d movies --type sqlite --out movies.sqlite writes plain SQLite.
botdb rm <db> moves a database to the trash for 30 days (botdb trash restore <db>).
botdb doctor checks the setup and explains anything that needs attention.

MCP

If the MCP server is configured (botdb mcp install), the same operations are available as tools: list_databases, create_database, schema, query (read-only), execute (writes and schema changes), history, sync.