rdb

CLI for ReadmeDB — persistent markdown file storage for AI agents.

The same files your AI agents read and write via MCP, now in your terminal.

Install

curl -fsSL https://app.readmedb.com/install.sh | sh

Or with a package manager:

npm install -g readmedb
pnpm add -g readmedb
yarn global add readmedb
bun install -g readmedb

Setup

Get your API key from app.readmedb.com/dashboard, then:

rdb login

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

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, save on exit

Command reference

Auth

| Command | Description | |---------|-------------| | rdb login | Save API key (prompts if not passed via --key) | | rdb login --key rdb_xxx | Non-interactive login | | rdb logout | Clear stored credentials | | rdb whoami | Show plan, quota bars, and recent files |

Files

| Command | Description | |---------|-------------| | rdb ls | List all files (newest first) | | rdb ls --limit 20 --offset 40 | Paginate | | rdb ls --since 2h | Files modified in the last 2 hours (s/m/h/d or ISO date) | | rdb cat <file> | Print file content to stdout | | rdb cat <file> --lines 1:50 | Partial read (1-indexed, inclusive) | | rdb cat f1.md f2.md f3.md | Bulk read up to 10 files | | rdb write <file> 'content' | Create or overwrite (content from arg) | | rdb write <file> --file local.md | Content from a local file | | cat local.md \| rdb write <file> | Content from stdin | | rdb write <file> -n | --no-clobber: skip if file already exists | | rdb append <file> 'more text' | Append to a file (creates if absent) | | rdb edit <file> | Open in $EDITOR, save on exit | | rdb rm <file> | Delete file and all version history (prompts) | | rdb rm <file> -y | Delete without confirmation | | rdb mv <from> <to> | Rename, preserving version history | | rdb mv <from> <to> --force | Overwrite destination if it exists |

Search & patch

| Command | Description | |---------|-------------| | rdb search 'query' | Full-text search with ranked snippets | | rdb patch <file> 'old' 'new' | Literal find-and-replace (first occurrence) | | rdb patch <file> 'old' 'new' --all | Replace all occurrences | | rdb patch <file> 'old' 'new' --nth 2 | Replace the 3rd occurrence (0-based) |

Version history

| Command | Description | |---------|-------------| | rdb history <file> | List version IDs, timestamps, and sizes | | rdb version <file> <id> | Print a specific historical version | | rdb diff <file> <id-a> | Diff version vs. current content | | rdb diff <file> <id-a> <id-b> | Diff two historical versions | | rdb diff <file> <id-a> -C 5 | Show 5 lines of context (default: 3) | | rdb restore <file> <id> | Make a historical version current (prompts) | | rdb restore <file> <id> -y | Restore without confirmation |

Global flags

| Flag | Description | |------|-------------| | --json | Output raw JSON on any command (useful for scripting) | | --help | Show help for any command | | --version | Print rdb version |

Scripting

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

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

# Write output of a command directly to a file
some-tool --output | rdb write output.md

# Check quota in CI
FILES=$(rdb whoami --json | jq '.fileCount')
echo "Using $FILES files"

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

Environment variables

| Variable | Description | |----------|-------------| | READMEDB_API_KEY | API key — takes priority over config file | | READMEDB_URL | Base URL override for self-hosted instances | | EDITOR | Editor used by rdb edit (falls back to vi) |

Links

• Dashboard
• Full docs
• ReadmeDB