RadiatorDB CLI

The radiatordb command-line tool reads and writes RadiatorDB documents directly through PostgreSQL. Use it for maintenance tasks, manual inspection, and small document edits.

Named document commands currently target normal collections only. They reject a collection that has an existing time-series storage parent.

Use RadiatorDB REST API when external applications need to read or write documents through Radiator Management API.

Configure the database URL

Pass the PostgreSQL URL for a RadiatorDB node with --url:

radiatordb --url postgresql://user:password@localhost/radiatordb collections

You can also set RADIATORDB_URL to avoid repeating --url for each command:

export RADIATORDB_URL=postgresql://user:password@localhost/radiatordb
radiatordb collections

When you use multiple RadiatorDB nodes, provide a comma-separated list:

export RADIATORDB_URL=postgresql://node1/radiatordb,postgresql://node2/radiatordb

List collections and keys

List collections that contain active documents:

radiatordb collections

List document keys in a collection:

radiatordb keys mycollection

Use --json when you need machine-readable output:

radiatordb keys mycollection --json

Read a document

Read one document by collection and key:

radiatordb get mycollection mydoc

The command prints the document as formatted JSON. For multipart keys, separate key parts with ~:

radiatordb get users mikem~example.com

Use --data to print only the document payload:

radiatordb get mycollection mydoc --data

Document keys use the same multipart-key format as RadiatorDB REST API. Use ~ to separate multipart key parts. Escape a literal ~ inside a key part as ~~:

radiatordb get users 'team~~alpha~alice'

Edit a document

Use get --data and put together to edit a document payload with a local editor. The --data flag prints only the payload from the document's data field, without metadata such as the key, revision, or timestamps:

radiatordb get mycollection mydoc --data > payload.json
edit payload.json
radiatordb put mycollection mydoc < payload.json

The put command reads JSON from standard input and stores it as the document data.

For example, this input writes a JSON object as the document payload:

{
  "username": "alice",
  "enabled": true,
  "roles": ["admin", "operator"]
}

Write it with:

radiatordb put users alice < payload.json

You can also pipe the payload directly:

echo '{"username":"alice","enabled":true}' | radiatordb put users alice

The key comes from the command argument. For multipart keys, separate key parts with ~:

echo '{"accounting":"started"}' | radiatordb put accounting helsinki~alice~session-1

Review archived revisions

List archived revisions for a document:

radiatordb revisions mycollection mydoc

Read a specific archived revision with --revision:

radiatordb get mycollection mydoc --revision 00000000-0000-0000-0000-000000000000

Export and import backups

Backup metadata records source time-series collection names and export bounds. Restore creates partitions from the target collection configuration. The standalone CLI does not register target time-series configuration. Therefore, CLI import cannot restore an included registered time-series collection.

Export a streaming JSON Lines backup to a file:

radiatordb export backup.jsonl

Export a gzip-compressed backup with --gzip:

radiatordb export --gzip backup.jsonl.gz

The export includes active documents and archived revisions by default. Use --no-revisions to export only active documents:

radiatordb export --no-revisions backup.jsonl

Use repeatable --include-collection options to export one or more exact collection names:

radiatordb export --include-collection users users.jsonl
radiatordb export \
  --include-collection users \
  --include-collection devices \
  selected.jsonl

Omit --include-collection to export every collection. Blank and duplicate names are rejected.

Use --timeseries-from and --timeseries-until to limit live time-series events. --timeseries-from is inclusive. --timeseries-until is exclusive. Either bound can be omitted. The same bounds apply to every included time-series collection. Bounds do not limit normal documents or revisions.

radiatordb export \
  --include-collection events \
  --timeseries-from 2026-07-01T00:00:00Z \
  --timeseries-until 2026-08-01T00:00:00Z \
  july-events.jsonl

Write the backup to standard output with -:

radiatordb export - > backup.jsonl

Import a backup from a file:

radiatordb import backup.jsonl

The import command accepts both raw JSON Lines backups and gzip-compressed backups by auto detecting the file format.

The import replaces existing data on all configured RadiatorDB nodes by default. The command prompts for confirmation. Use --yes for non-interactive restores.

Use repeatable --include-collection options for a filtered restore:

radiatordb import --yes --include-collection users users.jsonl

With the default reset strategy, a filtered import clears only the named collections. It preserves all excluded documents, revisions, and time-series partitions. An included collection is cleared even when the backup contains no rows for it. Omit the filter to reset the full database.

Use --no-revisions to skip revision lines without validating or restoring them:

radiatordb import --yes --no-revisions backup.jsonl

Use --strategy to merge backup documents into existing data instead of resetting the backend:

radiatordb import --yes --strategy skip backup.jsonl

Allowed strategies are reset, override, skip, and newest. reset is the default and is the only strategy that can import and validate revision records. Merge strategies skip revision lines unless you request revision import, which is rejected for those strategies. For strategy behavior, use cases, and caveats, see RadiatorDB Backup.

Read the backup from standard input with -:

radiatordb import --yes - < backup.jsonl

Wait for replication sync

Wait until all configured RadiatorDB nodes have synchronized their subscriptions:

radiatordb wait-sync

Use this before maintenance tasks that require every configured node to have caught up with replicated changes.

Destructive operations

The CLI also includes destructive maintenance commands. Use them only when you understand the effect on the configured RadiatorDB nodes.

• radiatordb disband removes replication subscriptions between all configured nodes.
• radiatordb destroy removes replication subscriptions and drops all configured databases.