r2db CLI

The r2db package supplies both the TypeScript SDK and the CLI. Node.js 22 or later is required. See the quickstart for installing the preview tarball.

Connect

r2db login --token-stdin
r2db whoami
r2db logout

Login targets the hosted service at https://r2db.dev unless you say otherwise. Pass --api <origin> for another deployment, or set R2DB_API_URL; the resolution order is the flag, then the environment variable, then your saved credentials, then the hosted default.

Credentials use the r2db configuration directory with owner-only permissions. Logout removes local credentials; revoke the token in the console to invalidate it. For automation, set R2DB_API_URL and R2DB_TOKEN as secrets.

Create from a schema

r2db create --name tasks --schema ./schema.ts

The TypeScript module exports schema or a default createSchema() result. The CLI bundles and loads it, derives the store schema, and creates empty indexed tables on the service. No application module, Rust toolchain, or base file is needed. Repeating the same name and schema resumes creation; a different schema under an existing name is refused. Use --json to receive the database ID and endpoint as JSON.

Read and check index coverage

r2db query --database ID --query '{"table":"task","limit":10}'
r2db explain --database ID --query '{"table":"task","limit":10}'

Both commands read a JSON AST from stdin when --query is absent. explain provides schema/index advice, not a measured execution plan. Writes and managed subscriptions are available through the SDK.

Optional: attach application code

r2db deploy --database ID --entry ./src/server.ts
r2db deploy --database ID --entry ./src/server.ts --export MyObject

Export a Workers-compatible fetch handler or DurableObject class. The service activates an immutable facet revision after startup validation. An invalid revision leaves previous code active; code updates preserve database data. Facet-local storage belongs to each revision and is not migrated automatically.

Advanced: upload an existing paged base

r2db init --name imported-db --file ./database.paged --entry ./src/server.ts
r2db deploy
r2db deploy --resume ID

This is the existing engine-format import path, not an arbitrary SQLite import. Bases use 64 KiB pages and checksummed 4 MiB parts. Configuration paths resolve relative to the configuration file; command-line paths resolve from the working directory. Ignore .r2db/ upload state. Existing r2db.json files are not overwritten.

Account resources

r2db list
r2db tokens
r2db credits

Use --json for machine-readable output. HTTPS is required except on localhost, and credentials are not forwarded through redirects. Progress goes to stderr, results to stdout, and failures exit with status 1.