readmedbv0.4
Sign inGet started
CLI · v0.4

rdb — your filesystem, in your shell.

Read, write, search, and version your readmedb files from any terminal — the same files your AI agents use.

Install

One-liner auto-detects bun, pnpm, yarn or npm and installs globally:

$curl -fsSL https://app.readmedb.com/install.sh | sh
npm
$ npm i -g readmedb
pnpm
$ pnpm add -g readmedb
yarn
$ yarn global add readmedb
bun
$ bun i -g readmedb

Setup

Grab your API key from the dashboard, then run:

$rdb login

This saves your key to ~/.config/rdb/config.json. You can also set READMEDB_API_KEY in your environment — it takes priority (useful in CI).

Self-hosted

$rdb login --url https://your-instance.example.com

Quick start

$ rdb whoami                        # check plan, quota, recent files
$ rdb ls                            # list all files
$ rdb write CLAUDE.md "# My notes" # create a file
$ rdb cat CLAUDE.md                 # read it back
$ rdb search "meeting notes"        # full-text search
$ rdb edit notes.md                 # open in $EDITOR

Auth

rdb loginSave API key (prompts if not passed via --key)
rdb login --key rdb_xxxNon-interactive login
rdb logoutClear stored credentials
rdb whoamiShow plan, quota, and recent files

Files

rdb lsList all files, newest first
rdb ls --limit 20 --offset 40Paginate
rdb ls --since 2hModified in last 2h (s/m/h/d or ISO date)
rdb cat <file>Print file content to stdout
rdb cat <file> --lines 1:50Partial read (1-indexed, inclusive)
rdb cat f1.md f2.md f3.mdBulk read up to 10 files
rdb write <file> 'content'Create or overwrite (content from arg)
rdb write <file> --file local.mdFrom a local file
cat local.md | rdb write <file>From stdin
rdb write <file> -n--no-clobber: skip if exists
rdb append <file> 'more'Append (creates if absent)
rdb edit <file>Open in $EDITOR, save on exit
rdb rm <file>Delete file and all versions (prompts)
rdb mv <from> <to>Rename, preserving version history
rdb search 'query'Full-text search with ranked snippets
rdb fetch 'auth architecture'Smart doc lookup — search + ranked reads in one call
rdb patch <file> 'old' 'new'Literal find-and-replace (first match)
rdb patch <file> 'old' 'new' --allReplace all occurrences
rdb patch … --nth 2Replace nth occurrence (0-based)

Version history

rdb history <file>List version IDs, timestamps, sizes
rdb version <file> <id>Print a specific historical version
rdb diff <file> <id-a>Diff version vs current
rdb diff <file> <id-a> <id-b>Diff two historical versions
rdb diff … -C 55 lines of context (default 3)
rdb restore <file> <id>Make a historical version current

Global flags

--jsonRaw JSON output on any command
--helpShow help for any command
--versionPrint rdb version

Scripting

Every command supports --json for machine-readable output.

# list files as JSON, parse with jq
$ rdb ls --json | jq '.[].name'

# write tool output directly into a file
$ some-tool --output | rdb write output.md

# check quota in CI
$ FILES=$(rdb whoami --json | jq '.fileCount')

# back up all files locally
$ rdb ls --json | jq -r '.[].name' | while read name; do
    rdb cat "$name" > "backup/$name"
  done

Environment variables

READMEDB_API_KEYAPI key — takes priority over config file
READMEDB_URLBase URL override for self-hosted instances
EDITOREditor used by rdb edit (falls back to vi)

Ready to get going?

Free plan — 50 files and 5 MB. No card.

Get your API key →Learn more