docs / reference

Configuration and environment

botdb's home directory, keystores, environment variables, automatic sync, output formats and defaults.

Settings are changed with commands (botdb use, botdb remote add --default) and can be overridden with environment variables and global flags.

Home directory

Everything botdb keeps on a device lives in its home directory: ~/.botdb by default, or --home <dir> / BOTDB_HOME. On Unix it’s created with mode 0700.

Path	Contents
`config.json`	Vault id, keystore, default database, databases joined without a vault, and botdb cloud account tokens. Mode `0600`.
`replicas/<db-id>.db`	The local copy of each database (plain SQLite with botdb’s bookkeeping tables), including the vault catalog.
`backups/<db-id>/<timestamp>.snap`	Automatic encrypted snapshots.
`vault.key`	The vault key, when the file keystore is used. Mode `0600`.
`locks/`	Lock files for background sync.
`relay/`	Default data directory of `botdb relay`.

Local copies are not encrypted by botdb. Rely on OS disk encryption (FileVault, BitLocker, LUKS) to protect them at rest. A replica file copied to another location gets a new replica id the next time botdb opens it, so the two copies never issue the same sequence numbers.

Keystore

The vault’s 256-bit master key is stored in:

Where	When
The OS keychain	macOS and Windows (service `botdb`). If writing to the keychain fails, botdb falls back to the file.
`<home>/vault.key` (mode `0600`)	Linux and other platforms, or anywhere with `BOTDB_KEYSTORE=file`.
Nowhere: derived from `BOTDB_PHRASE`	When `BOTDB_PHRASE` is set. Nothing is written to a keystore.

botdb vault status shows which one is in use.

Environment variables

Client

Variable	Description
`BOTDB_HOME`	Home directory. Same as `--home`. Default `~/.botdb`.
`BOTDB_FORMAT`	Output format: `json`, `table` or `csv`. Same as `-F`.
`BOTDB_DB`	Default database for commands that take `-d`.
`BOTDB_PHRASE`	Recovery phrase. Opens the vault without a keystore, for headless machines. It must belong to the vault this home is logged in to, if any (`vault_mismatch`).
`BOTDB_REMOTE`	Comma-separated remotes where the vault catalog syncs. Used with `BOTDB_PHRASE` on a fresh home.
`BOTDB_INVITE`	An invite (`bdb1_...`). botdb joins that database on first use and uses it when no database is selected. Works without a vault.
`BOTDB_KEYSTORE`	`file` stores the vault key in `<home>/vault.key` instead of the OS keychain.
`BOTDB_NO_AUTOSYNC`	`1`, `true` or `yes` turns off automatic sync. Run `botdb sync` yourself.
`BOTDB_RELAY_TOKEN`	Registration token sent when a database is first registered on a self-hosted relay that requires one.
`BOTDB_CLOUD_URL`	URL that `cloud` stands for. Default `https://botdb.dev`.

Relay

Variable	Default	Description
`BOTDB_RELAY_HOST`	`127.0.0.1`	Listen address (an IP address).
`PORT`	`8787`	Listen port.
`BOTDB_RELAY_DATA`	`<home>/relay`	Data directory.
`BOTDB_RELAY_TOKEN`		Token required to register new databases.
`BOTDB_RELAY_MAX_DB_BYTES`		Storage limit per database, in bytes.
`BOTDB_RELAY_RETENTION_DAYS`	`7`	Days to keep batches after a snapshot covers them.
`BOTDB_LOG`	`info`	Log filter (tracing `EnvFilter` syntax).

BOTDB_PHRASE, BOTDB_INVITE and BOTDB_RELAY_TOKEN are secrets. Pass them through your platform’s secret store (CI secrets, Docker secrets, an env file outside version control), not on the command line.

Automatic sync

botdb has no daemon. Instead:

Before reads (sql, schema, history, export, revert), botdb pulls a database if it hasn’t pulled in the last 10 seconds. It waits at most 2 seconds, or 20 seconds when the local copy is still empty, and then continues with whatever it has. Offline, reads just use the local copy.
After writes, botdb starts a detached botdb sync --background and returns immediately. That process syncs the vault catalog and the database, repeats while new local writes keep arriving, then runs maintenance.
Maintenance runs at most once an hour: a daily encrypted snapshot of each database (including the vault catalog), and purging databases that have been in the trash for more than 30 days.
The MCP server syncs in-process: shortly after writes and every 30 seconds.

BOTDB_NO_AUTOSYNC=1 turns all of this off. botdb sync and botdb sync --watch still work.

Global flags

Flag	Description
`--home <dir>`	Home directory.
`-F, --format <f>`	`json`, `table` or `csv`. Default: `table` on a terminal, `json` otherwise.
`-q, --quiet`	Suppress informational messages on stderr.

Output

Situation	Table format (terminal)	JSON (piped)
Query	Table, or `(no rows)`	Array of row objects
Write	`ok (N rows changed)`	`{"ok":true,"changes":N}`
Error	`error:` and `hint:` on stderr	`{"error":{"code","message","hint"}}` on stderr

Errors exit with status 1. Error output is JSON whenever the format is JSON or stderr isn’t a terminal.

Default database

Commands that take -d resolve the database in this order: -d <db>, BOTDB_DB, the database in BOTDB_INVITE, the default set with botdb use, then the only database if there is exactly one. The first database you create or join becomes the default automatically. -d accepts a name or an id prefix of at least 4 hex characters.

Default remotes

New databases sync to the default remotes chosen during botdb login (botdb cloud unless you picked something else). They’re stored in the vault, so all your devices use them, and the vault catalog syncs to them too.

botdb remote ls
botdb remote add cloud --default
botdb remote add https://relay.example.com --default
botdb remote rm ~/Dropbox/botdb --default

Changing the defaults doesn’t touch existing databases. Override per database with botdb create <name> --remote <url|path> or --no-remote, and later with botdb remote add|rm <url|path> -d <db>.