docs / reference

CLI reference

Every botdb command, argument and option.

botdb [--home <dir>] [-F json|table|csv] [-q] <command> [args]

Run botdb <command> --help for the same information in a terminal.

Global options

Output and errors

• Queries print rows: a table on a terminal, a JSON array of row objects otherwise, CSV with -F csv. An empty result prints (no rows) to stderr in table format.
• Writes print {"ok":true,"changes":N} as JSON, or ok (N rows changed) in table format.
• JSON is compact when stdout is not a terminal and indented when it is.
• Errors exit with status 1. When the format is JSON or stderr is not a terminal, they print JSON to stderr; otherwise error: and hint: lines.

{"error":{"code":"integer_primary_key","message":"...","hint":"..."}}

The code is stable and the hint says how to fix the problem.

Selecting a database

-d, --db <DB> takes a database name (case-insensitive) or an id prefix of at least 4 hex characters. Without it, botdb picks:

1. BOTDB_DB
2. the database in BOTDB_INVITE, if set
3. the default set with botdb use (the first database you create or join becomes the default)
4. the only database, if there is exactly one

Times

Options that take a <time> (--at, --since) accept:

Remotes

Any other scheme:// is rejected with invalid_remote.

Setup

botdb login

botdb login [--restore] [--remote <url|path|cloud>]... [--no-remote] [--phrase-stdin]

Creates a vault on this device, or restores an existing one.

Without --restore, botdb asks for a default remote, generates a vault and prints its 24-word recovery phrase. On a terminal it offers botdb cloud first, then the cloud folders it detects (iCloud Drive, Dropbox, Google Drive, OneDrive), each with a botdb subfolder, plus u to enter your own relay URL or another folder path and n for none. Without a terminal it doesn’t prompt: it uses the --remote values (botdb cloud if there are none, nothing with --no-remote) and prints {"vault","phrase","remotes"} as JSON. Choosing botdb cloud creates a free account for the vault; its token is stored in the vault, so your other devices use the same account.

With --restore, botdb reads the recovery phrase (from BOTDB_PHRASE, stdin, or a hidden prompt), asks where the vault syncs, pulls the vault catalog and then every database in it. It prints the restored databases and any remote errors.

Databases joined before logging in are added to the vault. A device that already has a vault fails with already_logged_in.

botdb logout

botdb logout --yes

Forgets the vault key on this device. Databases stay on disk; log back in with botdb login --restore. Without --yes it fails with confirm.

botdb vault

botdb vault phrase [--yes]
botdb vault verify [--phrase-stdin]
botdb vault status

Databases

botdb create

botdb create <name> [--remote <url|path>]... [--no-remote]

Creates a database with a new random id and key and adds it to the vault. Requires a vault (not_logged_in otherwise). It syncs to the default remotes unless you pass --remote (repeatable) or --no-remote.

Names use letters, digits, -, _ and ., start with a letter or digit, and are at most 64 characters.

botdb ls

botdb ls [--all]

Alias: botdb list. Lists databases with their id, remotes and notes (read-only, not in vault, in trash); * marks the default. --all includes databases in the trash.

botdb use

botdb use <db>

Sets the default database for commands that take -d.

botdb rename

botdb rename <db> <new-name>

Renames a database. The id, keys and data stay the same.

botdb rm

botdb rm <db>

Moves a database to the trash. Trashed databases are purged locally after 30 days.

botdb trash

botdb trash ls
botdb trash restore <db>
botdb trash empty [--remote] [--yes]

Data

botdb sql

botdb sql [-d <db>] [SQL] [-f <file>] [-p <value>]... [--params <json>] [--readonly]

Alias: botdb q. Runs SQL in SQLite’s dialect. The SQL comes from the argument, -f, or stdin (also when the argument is -). Several statements run atomically: all or nothing.

Parameters only work with a single statement (params_multi_statement). The output shows the last statement that returned rows; if none did, the total number of changed rows. On a database shared with you read-only, writes fail with read_only.

botdb sql "SELECT title FROM watched WHERE rating >= ?" -p 4
botdb sql "UPDATE watched SET rating = :r WHERE id = :id" --params '{"r": 5, "id": "a1b2"}'
botdb sql -f migrations/002_add_genre.sql
echo "SELECT count(*) AS n FROM watched" | botdb sql

See SQL support and table rules.

botdb schema

botdb schema [-d <db>] [table]

Shows tables (columns, row counts and CREATE statements), indexes and views, or a single table. Local-only tables are marked.

botdb history

botdb history [-d <db>] [table] [--pk <value>] [--since <time>] [--limit <n>]

Lists recorded changes, newest first: inserts, deletes, cell values and schema changes, with the time and the device that made them.

botdb revert

botdb revert [-d <db>] --at <time> [--table <t>]

Restores the database, or one table, to its state at <time>. botdb replays the change log up to that time, compares it with the current data and writes the difference as new changes, so the revert syncs, appears in history and can itself be reverted.

• Tables dropped since then are recreated (with a _restored suffix if the name is taken).
• Only columns that still exist are restored.
• A device that was bootstrapped from a snapshot without history can’t go back further than that snapshot (history_unavailable).

botdb export

botdb export [-d <db>] [--type json|csv|sqlite] [--table <t>] [--out <file>]

Exports data unencrypted.

botdb import

botdb import [-d <db>] <file> --table <t> [--type csv|json]

Inserts rows from a file into an existing table, in one transaction. The type defaults to JSON for .json files and CSV otherwise. CSV needs a header row of column names (values are imported as text); JSON must be an array of objects.

Sync and sharing

botdb sync

botdb sync [-d <db>] [--watch]

Pulls and pushes now. Without -d, it syncs the vault catalog and every database. Sync also runs automatically (see Automatic sync).

Fails with offline if no remote could be reached, or sync_failed if every remote failed.

botdb status

botdb status [-d <db>]

Shows the replica file and size, the number of changes (total and made on this device), the newest local snapshot and, per remote, pending changes, last pull, last push and last error.

botdb invite

botdb invite [db] [--read-only]

Prints an invite (bdb1_...) with the database’s keys and remotes. Invites are secrets. --read-only omits the write key; members with read-only access can only create read-only invites. As JSON: {"invite","database","read_only"}. Warns if the database has no remote.

botdb join

botdb join <invite> [--as <name>] [--remote <url|path>]...

Joins a database from an invite and downloads it.

join works without a vault: the database is kept in config.json (shown as not in vault) and added to the vault at the next botdb login. Joining a database you already have upgrades its key if the invite is newer or grants write access.

botdb rotate-key

botdb rotate-key [db]

Rotates a database’s keys. Remotes switch to the new keys and drop data from older key epochs, then everything is re-uploaded under the new key with a fresh snapshot. Your own devices pick up the new key through the vault catalog. Old invites stop working; re-invite the members you keep. Read-only members can’t rotate keys. See Sharing and invites.

botdb remote

botdb remote ls [-d <db>]
botdb remote add <url|path> [-d <db> | --default]
botdb remote rm <url|path> [-d <db> | --default]

botdb remote add cloud syncs through botdb cloud and creates an account if this vault doesn’t have one yet. Without --default, add and rm act on -d or the default database. With --default they change the default remotes for new databases. Defaults are stored in the vault, so your other devices use them too, and the vault catalog itself syncs to them. Existing databases keep their remotes. remote ls without -d lists the defaults and every database.

Backups

botdb backup

botdb backup create [--out <file>]
botdb backup restore <file> [--phrase-stdin]
botdb backup restore --remote [-d <db>] [--at <time>]
botdb backup ls [--remote] [-d <db>]

See Backups and recovery.

Servers and agents

botdb relay

botdb relay [--host <ip>] [--port <port>] [--data <dir>] [--token <t>] [--max-db-bytes <n>] [--retention-days <n>]

Runs a relay server. Put it behind a TLS reverse proxy.

Logging uses BOTDB_LOG (a tracing filter, default info). See Self-hosting a relay.

botdb mcp

botdb mcp
botdb mcp install [--client all|claude|opencode|codex|cursor|agents]

botdb mcp runs the MCP server on stdio. install registers it with agent clients; the default all only touches clients whose config directory exists. See Using with agents.

botdb skill

botdb skill
botdb skill install [--client all|claude|opencode|codex|cursor|agents] [--dir <dir>]

botdb skill prints the agent skill (SKILL.md, embedded in the binary). install writes it for agent clients, or to <dir>/botdb/SKILL.md with --dir. See Using with agents.

botdb cloud

botdb cloud [status]
botdb cloud signup

Shows your botdb cloud account: plan, databases used out of the plan’s limit, encrypted storage per database. signup creates the account explicitly; botdb login and botdb remote add cloud already do it. See botdb cloud.

botdb doctor

botdb doctor

Checks the vault, whether the recovery phrase was verified, the default remotes, whether every remote is reachable, and for each database: remotes, local copy, unsynced changes, sync errors and the age of the newest local snapshot. Each check is ok, warn or error, with a hint.

botdb completions

botdb completions <shell>

Prints a shell completion script for bash, elvish, fish, powershell or zsh.