Skip to main content

CLI Overview

This documentation provides a complete guide to using the LioranDB V2 Pre-Alpha CLI. It covers the available commands, configuration options, and essential CLI workflows for managing and interacting with LioranDB.

Install​

Install @liorandb/cli@1.0.6
npm i -g @liorandb/cli@1.0.6

The installed executable is:

liorandb

What the CLI actually does​

The liorandb binary is a source-backed wrapper around @liorandb/driver. Its job is not to replace the driver protocol logic, but to add operator workflow features on top of the real driver APIs.

From the current source, the CLI is responsible for:

  • persisting local profiles
  • persisting per-profile refresh-token sessions
  • validating and storing connection strings
  • resolving output modes for humans and automation
  • prompting before destructive actions
  • exposing direct data-plane commands
  • exposing admin and cluster maintenance commands
  • running an interactive shell with completion and history

Global options​

The root command in src/cli.ts registers these global options:

  • --profile <name>: select a saved CLI profile
  • --url <url>: override the stored URL for the current command only
  • --output <format>: choose table, json, ndjson, or quiet
  • --json: shortcut for --output json
  • --quiet: shortcut for --output quiet
  • --no-color: disable ANSI colors
  • --debug: include stack traces and lower-level driver diagnostics in errors

Behavior notes from the source:

  • --json and --quiet are formatting shortcuts, not separate commands
  • --url changes runtime behavior only and does not rewrite stored config
  • --profile changes both config lookup and session lookup
  • --debug affects rendering when a command fails

Command map​

Setup and config​

  • init
  • set url
  • set output
  • set db
  • set metrics-url
  • get url
  • get output
  • get metrics-url
  • config
  • profile list
  • profile create <name>
  • profile use <name>
  • profile show <name>
  • profile delete <name>

Authentication and sessions​

  • login
  • logout
  • whoami
  • sessions
  • revoke-session
  • change-password
  • auth login
  • auth logout
  • auth whoami
  • auth sessions
  • auth revoke-session
  • auth change-password

Database, collection, and direct document commands​

  • db list | create | drop | use | current
  • collection list | create | drop
  • find
  • find-one
  • find-by-ids
  • count
  • insert-one
  • insert-many
  • update-one
  • update-many
  • delete-one
  • delete-many
  • aggregate

Index commands​

  • index list
  • index create
  • index create-text
  • index drop

Admin commands​

  • user list | show | create | update | delete | reset-password | revoke-sessions
  • role list | show | create | update | delete
  • permission list
  • settings show | get | set
  • settings performance show | set
  • settings limits show | set
  • settings backups show | set
  • settings cors show | set
  • cors list | add | remove

Operational commands​

  • status
  • health
  • doctor
  • metrics
  • stats
  • cluster status | nodes | partitions | health | readiness | checkpoint | compact
  • backup list | create | show | verify | delete | restore | restore-job

Interactive mode​

  • shell

Typical first local flow​

Bootstrap CLI workflow
liorandb init
liorandb set url liorandb://admin:YOUR_PASSWORD@127.0.0.1:27018/default
printf '%s' "$LIORANDB_PASSWORD" | liorandb login admin --password-stdin
liorandb db use default
liorandb collection create products
printf '{"sku":"bk-001","title":"Blue Notebook","active":true}' | liorandb insert-one products --stdin
liorandb count products
liorandb shell

Output modes​

The shared printer supports four modes.

table​

Default human-readable output. Best for:

  • user list
  • cluster nodes
  • find products

json​

Pretty-printed JSON for one logical result payload. Best for:

  • automation with jq
  • inspecting exact field names
  • debugging server replies

ndjson​

One compact JSON object per line. Best for streaming record sets such as:

  • find

quiet​

Minimal output. Best for:

  • CI scripts that only need exit status
  • destructive operations where log noise should stay low

Representative usage:

Output mode examples
liorandb find users --filter "{\"active\":true}" --json
liorandb find users --filter "{\"active\":true}" --output ndjson
liorandb cluster checkpoint --yes --quiet

Local storage model​

The CLI stores two separate local state categories.

Config storage​

Managed through conf in src/config/config-store.ts.

Stored fields include:

  • current profile name
  • per-profile URL
  • per-profile output mode
  • per-profile selected database
  • per-profile raw metrics URL

Session storage​

Managed through src/auth/session-store.ts.

Stored fields include:

  • refresh token
  • session id
  • username
  • user id
  • update timestamps

Not stored:

  • plaintext passwords
  • short-lived access tokens

By default, session state lives under a .liorandb/state directory. The exact root can be overridden with LIORANDB_STATE_DIR.

Safety model​

The CLI includes several built-in safety checks from the real source:

  • db drop prompts unless --yes
  • collection drop prompts unless --yes
  • delete-many requires typing the collection name when the filter matches everything
  • backup delete prompts unless --yes
  • backup restore requires explicit restore confirmation unless --yes
  • shell input is parsed by a restricted JSON-like parser instead of arbitrary JavaScript

Mental model​

global flags
  -> runtime context
    -> selected profile
    -> output mode
    -> stored or overridden URL

command handler
  -> config/session lookup
  -> authenticated driver client when needed
  -> validation and safety prompts
  -> shared printer