Command-line interface
nonodb-cli is a small administrative client. On Linux and macOS, commands
that talk to the daemon use the Unix socket (NONODB_SOCK, default
/run/nonodb.sock) and, for TCP-backed setups, a bearer token
(NONODB_TOKEN). On Windows, daemon-facing commands use plaintext HTTP over TCP
(NONODB_URL, default http://127.0.0.1:7878). The CLI does not support TLS or
mTLS; use an official client for encrypted connections. File commands
(backup, inspect, restore) operate directly on an LMDB data directory on
every platform. The auth commands edit the auth registry file directly and do
not contact the daemon.
nonodb-cli <command> [arguments]Run nonodb-cli help for a summary.
Every daemon-facing command accepts --db <name> or NONODB_DB=<name> to select
a database. Without it, default is used. See
Multiple databases.
When several daemons run on one host, select one explicitly:
nonodb-cli instancesnonodb-cli --instance 11727 servernonodb-cli --socket /tmp/nonodb.sock replication status--instance accepts a PID or replication node id from the instance registry.
--socket sets the Unix socket directly. The registry is per-user and lives in
$XDG_RUNTIME_DIR/nonodb/instances, $HOME/.nonodb/instances, or the directory
named by NONODB_INSTANCE_DIR.
databases
Section titled “databases”Manage databases in one daemon:
nonodb-cli databases listnonodb-cli databases create app1nonodb-cli --db app1 find orders '{}'nonodb-cli databases drop app1list, create, and drop call list_databases, create_database, and
drop_database. A non-default database cannot be dropped while another active
request is using it.
Starts the embedded local web console and opens the browser:
nonodb-cli guinonodb-cli gui --port 8788nonodb-cli gui --no-opennonodb-cli gui --host 0.0.0.0 --allow-remotenonodb-cli gui --url http://127.0.0.1:7879nonodb-cli gui --cluster primary=http://127.0.0.1:7879,replica=http://127.0.0.1:7880--url makes the GUI proxy use daemon TCP with bearer-token authentication;
the Unix socket path is treated as trusted local admin.
--cluster enables the GUI Cluster tab and accepts a comma-separated list
of name=url nodes. The same list can be supplied through
NONODB_GUI_CLUSTER. Cluster probes use NONODB_CLUSTER_TOKEN, falling back to
NONODB_TOKEN. Cluster URLs currently must use http://; terminate TLS in a
local reverse proxy if the nodes require HTTPS.
The server listens on 127.0.0.1 by default. Non-loopback binds require
--allow-remote and should sit behind TLS/auth. It proxies /v1/exec, database-scoped
/<database>/v1/exec, /v1/watch, /healthz, /metrics, and replication API
paths to the daemon. The React assets are embedded in the CLI binary. See
GUI console.
Check that the daemon is reachable and healthy:
NONODB_SOCK=/tmp/nonodb.sock nonodb-cli ping{"ok": true}server
Section titled “server”Show the daemon’s actual listener addresses, including the resolved port
when NONODB_TCP uses :0, the Unix socket path, TLS state, and the advertised
replication URL:
NONODB_SOCK=/tmp/nonodb.sock nonodb-cli server{ "ok": true, "result": { "version": "0.26.0", "tcp": { "configured": "127.0.0.1:7902", "bound": "127.0.0.1:7902", "tls": false }, "unix": "/tmp/nonodb.sock", "advertise_url": "http://10.0.0.10:7902" }}This is the reliable way to distinguish a process that works locally but is not
reachable from another host. configured is the environment value; bound is
what the kernel actually accepted.
instances
Section titled “instances”List daemons that registered themselves in the per-user runtime registry:
nonodb-cli instancesnonodb-cli instances --jsonnonodb-cli instances pruneEach row includes PID, node id, role, liveness, Unix socket, TCP listener,
advertised replication URL, and data directory. prune removes records whose
process has exited. Registry files are runtime metadata only; they are not
backups and never contain tokens.
Choose one instance for a command with either selector:
nonodb-cli --instance 11727 replication statusnonodb-cli --instance liveapisec-local replication statusnonodb-cli --socket /Users/me/nd-replica/run/nonodb.sock replication status--instance and --socket are global options and can be placed before the
command.
Check readiness: the writer thread is running and LMDB can serve a read
transaction. Docker uses this command as its HEALTHCHECK.
NONODB_SOCK=/tmp/nonodb.sock nonodb-cli ready{"ok":true,"checks":{"writer":true,"storage":true,"storage_error":null}}Exit status is non-zero when the daemon returns HTTP 503.
collections
Section titled “collections”List known collections:
nonodb-cli collectionsCount documents in a collection, optionally with a filter:
nonodb-cli count usersnonodb-cli count users '{"active": true}'nonodb-cli count users '{"age": {"$gte": 18}}'The filter argument is JSON. It defaults to {}.
Query documents:
nonodb-cli find usersnonodb-cli find users '{"age": {"$gte": 18}}'nonodb-cli find users '{}' --sort age:desc --limit 20nonodb-cli find users '{"tenant":"acme"}' --sort created_at:desc --skip 40 --limit 20The filter must come before options. Defaults: no filter, limit=100, skip=0.
The output is pretty-printed JSON.
Run a SQL statement through the daemon:
nonodb-cli sql "SELECT team, COUNT(*) AS n FROM users GROUP BY team"nonodb-cli sql "SELECT name FROM users WHERE age >= $1" --param 18nonodb-cli sql --file report.sql--param is repeatable and accepts JSON values; unquoted values are treated as
strings. --file reads the statement from a file. The command prints the
result envelope and exits non-zero on an error.
Use shell for an interactive line-oriented SQL prompt:
nonodb-cli shellnonodb> SELECT COUNT(*) AS n FROM users;nonodb> .quitEach line is one statement. Use .quit, .exit, quit, or exit to leave.
indexes
Section titled “indexes”List secondary indexes for a collection:
nonodb-cli indexes usersThe output includes the index name, fields, uniqueness, and include fields.
reindex
Section titled “reindex”Rebuild all secondary, text, fuzzy, and vector indexes for a collection:
nonodb-cli reindex usersThis is the one-click migration/repair path after an index-format upgrade. It scans every document and blocks writes while the rebuild transaction runs. The command prints the rebuilt index names for each index type.
Show the LMDB address-space limit, high-water mark, and page size:
nonodb-cli map{ "map_size": 1073741824, "used_bytes": 7340032, "free_bytes": 1066401792, "page_size": 4096}events
Section titled “events”Show or configure automatic collection change events:
nonodb-cli events orders # shownonodb-cli events orders on status total # enable, only status/total updatesnonodb-cli events orders on # enable for any fieldnonodb-cli events orders off # disablenonodb-cli events tail # poll _events forevernonodb-cli events tail --type orders.update --filter '{"payload.after.status":"paid"}'nonodb-cli events tail --once # print one batch and exitEvents are written to _events in the same transaction as the data change.
See Outbox events.
subscriptions
Section titled “subscriptions”Persistent conditions over collection state, evaluated by the writer:
nonodb-cli subscribe orders paid --filter '{"status":"paid"}' --lease 600nonodb-cli subscribe orders many --count '{"filter":{"total":{"$gt":100}},"gt":100}'nonodb-cli subscribe orders high_once --filter '{"total":{"$gt":100}}' --oncenonodb-cli subscribe orders changed --ops update --type custom.orders_changednonodb-cli subscription-ping orders paid 600nonodb-cli subscriptions ordersnonodb-cli unsubscribe orders paidBy default every matching write emits. --once is optional and switches to
edge-triggered (false -> true). Persistent subscriptions have a client lease
(default 600 seconds); run subscription-ping before it expires. Events are
stored in _events with type subscription.<name> unless --type is given. See
Conditional subscriptions.
history
Section titled “history”Show or set per-collection revision history retention:
nonodb-cli history users # show the current settingnonodb-cli history users 50 # retain up to 50 revisions per documentnonodb-cli history users 0 # disable new history writesHistory is configured per collection. There is no daemon-wide history switch.
resize
Section titled “resize”Grow the LMDB map without restarting the daemon:
nonodb-cli resize 4GiBnonodb-cli resize 4294967296{"old_size": 1073741824, "map_size": 4294967296}The size must be page-aligned and at least the current map size. The command
waits for active transactions; use a longer NONODB_TIMEOUT if a large write
is in progress. It only grows the map. To shrink the reservation, stop the
daemon, lower NONODB_MAP_SIZE, and restart; the file itself only shrinks via a
compacting backup/restore. Do not run backup or inspect concurrently with
an online resize.
Force an fsync of the selected database:
nonodb-cli --db app1 sync{"synced": true}Use it after a bulk import written with durability="relaxed" or "unsafe".
The operation requires database-admin scope and is separate from per-request
durability in the HTTP API.
Send an arbitrary /v1/exec request:
nonodb-cli exec '{"op":"create_text_index","coll":"articles","field":"body"}'nonodb-cli exec '{"op":"search","coll":"articles","field":"body","query":"rust","limit":5}'nonodb-cli exec '{"op":"write_batch","ops":[ {"op":"insert","coll":"audit","doc":{"event":"login"}}, {"op":"update","coll":"counters","filter":{"_id":"logins"},"update":{"$inc":{"n":1}}}]}'This is the escape hatch for operations not wrapped by a dedicated command. It prints the full response envelope.
backup-keygen
Section titled “backup-keygen”Generate an age X25519 identity and recipient for encrypted backups:
nonodb-cli backup-keygen /etc/nonodb/backup-identity.txtThe identity is written to the file with mode 0600; the public
age1... recipient is printed to stdout. Store the identity outside the daemon
and set NONODB_BACKUP_IDENTITY_FILE when restoring an encrypted backup.
backup
Section titled “backup”Create a consistent, compacted copy of one database. In the multi-database
layout the source is ./data/<database>/ (or legacy ./data/):
nonodb-cli --db app1 backup ./data ./backupbackup: ./data/app1 -> ./backup/data.mdbmanifest: ./backup/manifest.json (sha256 ...)- The source is opened read-only.
- The copy can be made while the daemon is running.
CompactionOption::Enabledomits free pages, so the backup is usually smaller than the livedata.mdb.- The output directory is created if needed.
- Only the selected database’s
data.mdbis copied.lock.mdbis not part of the backup. - The copy is synced to disk before the command exits.
manifest.jsonrecords the source, timestamp, file size, and SHA-256.
The resulting directory is a one-database backup, not an instance root. To inspect and verify it directly:
nonodb-cli inspect ./backupnonodb-cli verify-backup ./backupbackup-all
Section titled “backup-all”Back up every database under an instance root:
nonodb-cli backup-all /var/lib/nonodb /var/backups/nonodb/instanceIt writes instance/manifest.json plus <database>/data.mdb and
<database>/manifest.json for each database. Each database copy is consistent
on its own, but the set is not atomic across databases. The auth registry is
not copied.
restore-all
Section titled “restore-all”Restore every database listed in an instance manifest:
nonodb-cli restore-all /var/backups/nonodb/instance /var/lib/nonodb --force --verifyStop the daemon first. Existing database files require --force; databases not
listed in the manifest are left untouched.
verify
Section titled “verify”Deep-check a data directory without a manifest:
nonodb-cli --db app1 verify ./datanonodb-cli --db app1 verify ./data --jsonThe command opens the database read-only and checks:
- the schema version and collection registry;
- every document’s JSON and
_idconsistency; - every secondary index entry against its document;
- full-text postings, document lengths, and total token counts;
- fuzzy trigram posting counts;
- history and TTL entry counts.
Legacy index formats are counted but not reconstructed exactly.
verify-backup
Section titled “verify-backup”Verify manifest.json, the SHA-256 checksum, and the full database:
nonodb-cli verify-backup ./backupnonodb-cli verify-backup ./backup --jsonThe JSON form returns both the manifest and the verification report. A non-zero exit status means the backup must not be used.
manifest: source=./data created_at_ms=... size=... sha256=...verified: ./backupschema: 1collections: 2documents: 1000...restore drill
Section titled “restore drill”scripts/restore_drill.py automates the full backup → verify → restore →
query cycle. See Backup and restore.
inspect
Section titled “inspect”Print database and per-collection document counts without starting the daemon:
nonodb-cli inspect ./data # default databasenonodb-cli --db app1 inspect ./datanonodb-cli inspect ./data usersdata: ./datacollections: 2 users: 1000 settings: 12With a multi-database instance root, add --db or pass the database directory
directly (for example ./data/app1). Without --db, the command resolves the
legacy root or default/.
If a collection is given, only that collection is printed. The command opens the environment read-only with room for all named databases. The daemon should normally be stopped, or at least not writing, while inspecting; LMDB still provides a consistent read snapshot.
restore
Section titled “restore”Restore a backup into a data directory:
# Stop the daemon first.systemctl stop nonodb
nonodb-cli restore ./backup ./data --forcenonodb-cli restore ./backup ./data --force --verifyrestore: ./backup/data.mdb -> ./data/default/data.mdbverified: ./data/default...Rules and warnings:
- Stop the daemon before restoring. Replacing
data.mdbunder a running process is unsafe. --forceis required when the destinationdata.mdbalready exists.- With a multi-database root, the default target is
default/data.mdb; use--dbto restore another database. - The command removes a stale
lock.mdbfrom the destination. - The backup can be either a directory containing
data.mdbor a direct path to adata.mdbfile. - If the backup directory has
manifest.json, its size and SHA-256 are checked before copying. --verifydeep-checks the restored directory after the copy.- Start the daemon after the restore and verify counts and indexes.
Manage the file-based principal registry. The default path is
NONODB_AUTH_FILE, or /etc/nonodb/auth.json on Unix (auth.json on Windows).
All commands validate the complete file and write it atomically.
Create a registry with an admin principal (*:*):
nonodb-cli auth initIt does not create a token. Create one next:
nonodb-cli auth token create adminThe printed token (nodb_<kid>_<secret>) is shown only once. The file stores
kid plus SHA-256 of the secret.
Principals and scopes:
nonodb-cli auth principal listnonodb-cli auth principal add app read:orders,write:ordersnonodb-cli auth principal scopes app read:orders,write:orders,read:customersTokens:
nonodb-cli auth token listnonodb-cli auth token create app [kid]nonodb-cli auth token disable <kid>nonodb-cli auth token enable <kid>Certificates (SHA-256 of the DER-encoded leaf certificate, lowercase hex):
nonodb-cli auth cert listnonodb-cli auth cert add <sha256> appnonodb-cli auth cert disable <sha256>nonodb-cli auth cert enable <sha256>Validate the file without changing it:
nonodb-cli auth checkUse auth init --force only when you intentionally want to replace the whole
registry. The daemon reloads valid changes within about one second; an invalid
change is rejected and the daemon keeps the last known good configuration.
The same principals, tokens, and certificates can be managed with the
/v1/auth HTTP API or the GUI Authorization tab when the daemon has an
enabled admin:db credential. CLI commands keep working directly on the file
and are the recovery path.
See Authentication and authorization for the file schema, scope grammar, audit log, and mTLS setup.
replication
Section titled “replication”Inspect the durable log and replica status for the selected database:
nonodb-cli replication statusnonodb-cli replication primarynonodb-cli replication changes 0 100Inspect replica acknowledgements:
nonodb-cli replication acksPrune a known-acked range, refusing to pass the minimum replica ack:
nonodb-cli replication prune 1234 --require-acksPause, resume, or disconnect a replica without deleting data:
nonodb-cli replication pausenonodb-cli replication resumenonodb-cli replication disconnectRemove a stale acknowledgement from the primary after a replica is disconnected (GUI: Remove replica):
nonodb-cli replication forget replica-prodThis deletes the ACK row and blocks further ACKs from that node id until a new
pairing code is redeemed. A still-running replica will receive
403 replica_removed; use pause or disconnect on that replica to stop it.
pause keeps the source and token; resume continues from the stored source.
disconnect removes both and leaves the node read-only. Promote it separately
with replication promote <epoch> if it should become standalone.
Change the pull source without restarting the daemon:
nonodb-cli replication source https://new-primary:7878 default,app1 1Create a one-time 8-character code on the primary and enroll a new replica:
# primarynonodb-cli replication add-replica replica-eu default# alias: nonodb-cli replication pair replica-eu default
# new replica, after starting its daemon with NONODB_REPLICATION_ROLE=replicanonodb-cli replication join https://primary.example.com:7878 K7M4-P9QXUse the primary’s daemon API URL, not the GUI proxy. The default API port is
7878; if NONODB_TCP uses another port, use that port (the GUI Write URL
field shows the effective value). The CLI prints the same URL when it creates a
pairing code.
replication join is a local admin command: the CLI talks to the local
replica daemon, and that daemon redeems the code against <primary-api-url>.
It does not connect directly to the primary URL. If you see:
nonodb-cli: connect: No such file or directory (os error 2)the local daemon socket is missing or NONODB_SOCK points at the wrong path.
Start the replica daemon first, or set NONODB_SOCK to its actual socket
(e.g. /run/nonodb-replica.sock or /tmp/nonodb.sock). On macOS/Linux the CLI
uses the Unix socket; NONODB_URL is the Windows TCP path and is ignored on
Unix. If the daemon runs in Docker, run the command inside the container with
the container’s socket path.
On success the CLI prints a short confirmation instead of raw JSON:
Connected to the cluster. node_id: replica-eu source: https://primary.example.com:7878 databases: default,app1 role: replica pulling: https://primary.example.com:7878The primary GUI shows this replica after its first acknowledgement.Set NONODB_REPLICATION_ADVERTISE_URL on the replica if the primary GUI should
automatically probe its metrics in the Cluster view.
The code can be omitted from join; the CLI prompts for it. List and revoke
pending codes with:
nonodb-cli replication pairingsnonodb-cli replication revoke K7M4-P9QXThe code is single-use, valid for 10 minutes, and only bootstraps a cluster credential.
Manually switch roles with an expected epoch:
nonodb-cli replication promote 0nonodb-cli replication promote 0 --force # only when the old source is unreachablenonodb-cli replication demote 1 replicanonodb-cli replication demote 1 replica https://new-primary:7878The optional successor URL is stored on the demoted node. Replicas pulling from it switch their source automatically.
A stale epoch is rejected with 409. The role is persisted in the hidden node
metadata collection <NONODB_DATA>/.node; it wins over
NONODB_REPLICATION_ROLE after the first start.
NONODB_DB=app1 or --db app1 selects another database. Status includes role,
read-only mode, source URL, bootstrap mode, applied sources, lag, promotion
readiness, and the last transport/apply error. Pruning is an administrative retention action; do not
prune sequences that replicas still need.
Environment
Section titled “Environment”| Variable | Default | Used by |
|---|---|---|
NONODB_SOCK |
/run/nonodb.sock |
Daemon-facing commands on Linux/macOS |
NONODB_INSTANCE_DIR |
user runtime dir | Override the local instance registry directory |
NONODB_URL |
http://127.0.0.1:7878 |
Daemon-facing commands on Windows |
NONODB_TOKEN |
— | Bearer token for daemon-facing commands |
NONODB_AUTH_FILE |
/etc/nonodb/auth.json (Unix) |
Registry used by auth commands |
NONODB_DB |
default |
Database selected by daemon-facing commands |
backup, inspect, restore, and auth do not use the socket or token.
auth commands edit the local auth file directly.
Typical procedures
Section titled “Typical procedures”Online backup
Section titled “Online backup”TS=$(date -u +%Y%m%dT%H%M%SZ)nonodb-cli backup-all /var/lib/nonodb /var/backups/nonodb/$TSnonodb-cli inspect /var/backups/nonodb/$TS/defaultFor a single database, use nonodb-cli --db app1 backup ....
Restore after an incident
Section titled “Restore after an incident”systemctl stop nonodbnonodb-cli restore-all \ /var/backups/nonodb/20261109T120000Z /var/lib/nonodb --force --verifysystemctl start nonodbNONODB_SOCK=/run/nonodb/nonodb.sock nonodb-cli --db app1 count usersRaw query for automation
Section titled “Raw query for automation”nonodb-cli exec '{"op":"find","coll":"jobs","filter":{"state":"queued"},"limit":1}'The CLI exits with a non-zero status when a daemon or file operation fails.