Skip to main content

Admin, Ops, and Shell

The CLI covers a lot more than login and CRUD. The source includes full admin and operational workflows.

User commands​

The CLI supports:

  • user list
  • user show <id-or-username>
  • user create <username>
  • user update <id>
  • user delete <id>
  • user reset-password <id>
  • user revoke-sessions <id>

Useful flags:

  • user create --role <role...>
  • user create --must-change-password
  • user update --enabled
  • user update --disabled
  • user update --role <role...>
  • user update --metadata <json>
  • user delete --yes

Important source-backed behavior:

  • user show accepts either a user id or username
  • if direct lookup by id fails, the CLI falls back to listing users and matching by username
  • user update --enabled and user update --disabled are mutually exclusive
  • user update --metadata <json> requires a JSON object and stringifies non-string values
  • user delete prompts unless --yes
  • user reset-password always prompts for the new password interactively
  • user revoke-sessions revokes every session for that user, not just one session id

Example:

User management
liorandb user list
liorandb user create analyst --role read-only --must-change-password
liorandb user update 01K2USER --enabled --metadata "{\"team\":\"ops\"}"
liorandb user revoke-sessions 01K2USER

Role and permission commands​

The CLI supports:

  • role list
  • role show <id>
  • role create <name>
  • role update <id>
  • role delete <id>
  • permission list

Grant strings are parsed in the form:

Permission@cluster
Permission@db.collection

Important source-backed behavior:

  • before parsing grants, the CLI fetches the server-advertised permission set
  • grant text is validated against that live permission set
  • role create and role update can prompt for grants interactively when none are provided
  • role delete looks up the role first so it can confirm using the human-readable role name
  • permission list renders the permission names currently advertised by the server, not a hard-coded local list

Example:

Roles and permissions
liorandb permission list
liorandb role create read-users --grant ReadDocuments@default.users
liorandb role update 01K2ROLE --grant ReadDocuments@default.users WriteDocuments@default.users

Settings and CORS​

The CLI supports:

  • settings show
  • settings get <key>
  • settings set <key> <value>
  • settings performance show
  • settings performance set
  • settings limits show
  • settings limits set
  • settings backups show
  • settings backups set
  • settings cors show
  • settings cors set
  • cors list
  • cors add <origin>
  • cors remove <origin>

The settings layer has a useful source detail:

  • it decodes strings like true, false, null, numbers, objects, and arrays into human-readable values when printing
  • it validates JSON-looking values before sending them back

liorandb settings show​

Shows the generic key/value settings map returned by the server.

The CLI decodes string-like values into:

  • booleans
  • null
  • numbers
  • arrays
  • objects

when possible, so the output is easier to read.

liorandb settings get <key>​

Shows one decoded setting value by key.

If the key does not exist, the command fails with a CLI error.

liorandb settings set <key> <value>​

Writes one generic setting key.

The CLI:

  • keeps plain strings as strings
  • preserves JSON-looking arrays and objects after validating them
  • preserves scalar booleans, null, and numbers as raw values

Structured settings commands​

The CLI also exposes typed settings surfaces from the driver:

  • settings performance show | set
  • settings limits show | set
  • settings backups show | set
  • settings cors show | set

These commands:

  • read the current structured object from the server
  • or replace the full structured object using --json, --file, or --stdin

CORS convenience commands​

The standalone cors group is a convenience wrapper over the structured CORS settings API.

  • cors list prints allowed_origins
  • cors add <origin> appends an origin if not already present
  • cors remove <origin> removes one origin from the list
Settings and CORS
liorandb settings show
liorandb settings get max_connections
liorandb settings set max_connections 500
liorandb settings performance show
liorandb settings limits show
liorandb settings backups show
liorandb settings cors show
liorandb cors add https://app.example.com
liorandb cors list

Status, doctor, metrics, and stats​

The main operations commands are:

  • status
  • health
  • doctor
  • metrics
  • stats

Example:

Diagnostics
liorandb status
liorandb doctor
liorandb metrics
liorandb metrics --raw --metrics-url http://127.0.0.1:27201/metrics
liorandb stats

Source-backed behavior worth knowing:

  • status combines unauthenticated liveness/readiness checks with authenticated cluster APIs
  • doctor runs lightweight checks for configuration, DNS, HTTP reachability, readiness, authentication, gRPC discovery, and cluster health
  • metrics without --raw derives a summary from authenticated APIs
  • metrics --raw fetches a literal metrics endpoint and requires either --metrics-url, a stored profile metricsUrl, or LIORANDB_METRICS_URL
  • status and metrics both support --watch and --interval <seconds>

liorandb status​

Combines:

  • unauthenticated /live
  • unauthenticated /ready
  • unauthenticated server-info lookup
  • authenticated cluster summary
  • authenticated cluster health

into one operator summary.

liorandb health​

Prints partition-health rows including:

  • partition id
  • role
  • read-only state
  • leader and replica LSNs
  • WAL in-flight data
  • checkpoint timing

liorandb doctor​

Runs lightweight diagnostics for:

  • configuration validity
  • DNS lookup
  • HTTP endpoint reachability
  • readiness reachability
  • authentication
  • gRPC discovery
  • cluster health

liorandb metrics​

Without --raw, prints a metrics summary derived from authenticated APIs.

With --raw, fetches a literal metrics endpoint and requires:

  • --metrics-url <url>, or
  • a stored profile metrics URL, or
  • LIORANDB_METRICS_URL

liorandb stats​

Shows available high-level inventory data such as:

  • database count
  • collections per database
  • cluster node count
  • partition count
  • cluster healthy flag

Cluster commands​

The cluster subgroup supports:

  • cluster status
  • cluster nodes
  • cluster partitions
  • cluster health
  • cluster readiness
  • cluster checkpoint
  • cluster compact

The source protects mutating cluster operations with confirmation prompts unless --yes is passed.

liorandb cluster status​

Shows cluster summary fields such as:

  • node id
  • cluster state
  • node count
  • partition count
  • protocol version

liorandb cluster nodes​

Lists cluster nodes and their listen/public/metrics addresses.

liorandb cluster partitions​

Lists partition placement, leaders, and replica assignments.

liorandb cluster health​

Prints the same partition-health view used by top-level health.

liorandb cluster readiness​

Shows:

  • current readiness state
  • readiness transition count
  • transition rows with state, timestamp, and reason

liorandb cluster checkpoint​

Triggers a cluster checkpoint maintenance operation.

Behavior:

  • prompts unless --yes
  • reports acceptance rather than low-level checkpoint internals

liorandb cluster compact​

Triggers cluster compaction.

Behavior:

  • prompts unless --yes
Cluster operations
liorandb cluster status
liorandb cluster nodes
liorandb cluster partitions
liorandb cluster readiness
liorandb cluster checkpoint --yes
liorandb cluster compact --yes

Backup commands​

The CLI supports:

  • backup list
  • backup create
  • backup show <id>
  • backup verify <id>
  • backup delete <id>
  • backup restore <id>
  • backup restore-job <id>

Important safety behaviors in the source:

  • backup delete prompts for confirmation unless --yes
  • backup restore requires typing RESTORE <backup-id> unless --yes
  • backup restore also supports --disable-safety-backup
  • backup create --scope only accepts cluster or local_node

liorandb backup list​

Lists backup jobs.

liorandb backup create​

Creates a backup job.

Supported options:

  • --label <label>
  • --scope <scope>

liorandb backup show <id>​

Shows a backup record in detail.

liorandb backup verify <id>​

Runs backup verification for one backup id.

liorandb backup delete <id>​

Deletes a backup record and associated archive.

liorandb backup restore <id>​

Schedules a restore.

Supported options:

  • --yes
  • --disable-safety-backup

liorandb backup restore-job <id>​

Shows a scheduled restore job in detail.

This is useful after a restore request when you want to inspect:

  • restore job status
  • failure details
  • safety backup id
  • validation results
  • per-node progress

Example:

Backups
liorandb backup list
liorandb backup create --label nightly --scope cluster
liorandb backup show 01K2BACKUP
liorandb backup verify 01K2BACKUP
liorandb backup restore 01K2BACKUP
liorandb backup restore-job 01K2RESTORE

Interactive shell​

The shell implementation in src/shell/repl.ts and src/shell/parser.ts is one of the most detailed parts of the CLI.

Start it with:

Start shell
liorandb shell

What the shell supports​

  • profile-aware prompt with current database
  • persistent history
  • tab completion for meta commands, databases, collections, and db.<collection>.<operation>
  • multiline input
  • safe JSON-like parsing instead of arbitrary JavaScript execution
  • in-shell login and logout
  • shell access to newer CLI surfaces such as readiness, settings, backups, count, ID lookup, and indexes

Meta commands​

The parser exposes these dot-commands:

  • .help
  • .exit
  • .quit
  • .status
  • .whoami
  • .databases
  • .use <database>
  • .db.create <database>
  • .db.drop <database>
  • .db.current
  • .collections
  • .collection.create <name>
  • .collection.drop <name>
  • .collection.list
  • .users
  • .roles
  • .permissions
  • .cluster.status
  • .cluster.nodes
  • .cluster.partitions
  • .cluster.health
  • .cluster.readiness
  • .cluster.checkpoint
  • .cluster.compact
  • .settings
  • .settings.performance
  • .settings.limits
  • .settings.backups
  • .settings.cors
  • .backup.list
  • .backup.create [label] [scope]
  • .backup.show <backupId>
  • .backup.verify <backupId>
  • .backup.delete <backupId>
  • .backup.restore-job <jobId>
  • .metrics
  • .stats
  • .clear
  • .history
  • .login
  • .logout

Data expressions​

The shell supports:

  • db.users.find(filter?, options?)
  • db.users.findOne(filter?, options?)
  • db.users.findManyByIds([ids])
  • db.users.countDocuments(filter?)
  • db.users.insertOne(document)
  • db.users.insertMany([documents])
  • db.users.updateOne(filter, update, options?)
  • db.users.updateMany(filter, update, options?)
  • db.users.deleteOne(filter)
  • db.users.deleteMany(filter)
  • db.users.createIndex(definition)
  • db.users.createTextIndex(field, options?)
  • db.users.listIndexes()
  • db.users.dropIndex(name)
  • db.users.aggregate(pipeline)

Example session:

Shell example
liorandb [default]> db.users.insertOne({name:'Ada', active:true})
{
  "inserted_id": "01K2EXAMPLE"
}

7ms

liorandb [default]> db.users.find({active:true}, {limit: 10})
+------+--------+
| name | active |
+------+--------+
| Ada  | true   |
+------+--------+

1 document
4ms

liorandb [default]> db.users.countDocuments({active:true})
{
  "count": 1
}

2ms

JSON-like parser rules​

The shell parser accepts:

  • strict JSON
  • single-quoted strings
  • unquoted simple object keys
  • multiline arrays and objects

It does not evaluate arbitrary JavaScript. That is a deliberate safety decision in the source.