Skip to main content

Data and CRUD

Learn how to use data and CRUD operations in the LioranDB CLI to create, read, update, and delete documents. Understand how to work with databases and collections directly from the command line.

Database commands​

The db group supports:

  • db list
  • db create <name>
  • db drop <name>
  • db use <name>
  • db current

liorandb db list​

Lists databases visible to the current authenticated account.

Human output marks the current database when one is selected.

JSON output includes:

  • current_database
  • databases

liorandb db create <name>​

Creates a database through the driver API.

JSON output includes:

  • created
  • database

liorandb db drop <name>​

Drops a database through the driver API.

Safety behavior from the source:

  • prompts before deletion unless --yes
  • if the dropped database was stored as the active profile database, the CLI clears that stored field

JSON output includes:

  • dropped
  • database

liorandb db use <name>​

Persists the active database for the selected profile.

This does not create the database. It only updates local CLI config.

JSON output includes:

  • selected
  • database
  • profile

liorandb db current​

Prints the currently active database resolved for the selected profile.

If no database can be resolved, this command fails with a CLI error.

Example​

Database workflow
liorandb db list
liorandb db create app
liorandb db use app
liorandb db current

Important source behavior:

  • db use persists the selected database into the current profile
  • db drop prompts for confirmation unless --yes is passed
  • if you drop the profile's active database, the CLI clears that stored database field

Collection commands​

The collection group supports:

  • collection list
  • collection create <name>
  • collection drop <name>

All collection commands support --db <database> to override the active database.

liorandb collection list​

Lists collections in the resolved database.

JSON output includes:

  • database
  • collections

liorandb collection create <name>​

Creates a collection in the resolved database.

JSON output includes:

  • created
  • database
  • collection

liorandb collection drop <name>​

Drops a collection in the resolved database.

Safety behavior from the source:

  • prompts before deletion unless --yes

JSON output includes:

  • dropped
  • database
  • collection
Collection workflow
liorandb collection list
liorandb collection create users
liorandb collection drop old-users --yes

JSON input and query input styles​

CRUD commands use helpers from src/utils/input.ts and accept JSON from:

  • inline --json
  • --file <path>
  • --stdin
  • --ndjson <path> for insert-many

That makes the CLI usable for:

  • one-off manual invocations
  • CI and deployment scripts
  • shell pipelines
  • checked-in JSON request files

Shared query flags​

Several data commands share the same query-oriented option set:

  • --db <database>
  • --filter <json>
  • --filter-file <path>
  • --stdin
  • --limit <number>
  • --skip <number>
  • --sort <json>
  • --projection <json>

These are used by:

  • find
  • find-one
  • count
  • update-one
  • update-many
  • delete-one
  • delete-many

Insert commands​

Insert commands
liorandb insert-one users --json "{\"name\":\"Ada\",\"active\":true}"
liorandb insert-many users --file ./users.json
liorandb insert-many users --ndjson ./users.ndjson

Representative output:

Insert output
{
  "database": "default",
  "collection": "users",
  "inserted_id": "01K2EXAMPLE"
}

Find commands​

The CLI supports:

  • find <collection>
  • find-one <collection>
  • find-by-ids <collection>
  • count <collection>

liorandb find <collection>​

Returns multiple matching documents.

Behavior notes:

  • in ndjson mode, one document is emitted per line
  • in table mode, the cursor is materialized and printed as rows
  • in json mode, output is shaped as {documents, count}

liorandb find-one <collection>​

Returns the first matching document or no result.

Behavior notes:

  • in human mode, when no document matches, the CLI prints No document matched.
  • in JSON mode, missing results are printed as {document: null}

liorandb find-by-ids <collection>​

Looks up multiple IDs in one call while preserving input order.

Input options:

  • --json <json>
  • --file <path>
  • --stdin

Behavior notes:

  • expects a JSON array of ids
  • missing ids are returned as null
  • JSON output includes both ids and documents

liorandb count <collection>​

Counts matching documents.

Behavior notes:

  • in human mode it prints the numeric count directly
  • in JSON mode it prints {count}

Example:

Find commands
liorandb find users --filter "{\"active\":true}" --sort "{\"name\":1}" --limit 20
liorandb find-one users --filter "{\"email\":\"ada@example.com\"}"
liorandb find-by-ids users --json "[\"user-1\",\"user-2\",\"missing-id\"]"
liorandb count users --filter "{\"active\":true}"

Update commands​

The CLI registers:

  • update-one <collection>
  • update-many <collection>

Extra update flags:

  • --update <json>
  • --update-file <path>
  • --upsert
Update examples
liorandb update-one users --filter "{\"email\":\"ada@example.com\"}" --update "{\"$set\":{\"active\":false}}"
liorandb update-many users --filter "{\"active\":false}" --update "{\"$set\":{\"flagged\":true}}" --upsert

Representative output:

Update output
{
  "database": "default",
  "collection": "users",
  "matched_count": 1,
  "modified_count": 1,
  "upserted_id": null
}

Delete commands​

The CLI registers:

  • delete-one <collection>
  • delete-many <collection>

There is one especially important safety guard in the source:

  • delete-many asks for an exact collection-name confirmation when the filter matches everything, unless --yes is passed
Delete examples
liorandb delete-one users --filter "{\"email\":\"ada@example.com\"}"
liorandb delete-many users --filter "{}"
liorandb delete-many users --filter "{}" --yes

Aggregation​

liorandb aggregate <collection>​

The aggregate command expects a JSON array pipeline:

Aggregate
liorandb aggregate users --json "[{\"$match\":{\"active\":true}},{\"$sort\":{\"name\":1}}]"

If the provided pipeline is not an array, the command throws a CLI error.

Index commands​

The CLI now exposes the driver's index-management surface through the index command group.

liorandb index list <collection>​

Lists indexes for the target collection.

Supported option:

  • --db <database>

JSON output includes:

  • indexes

liorandb index create <collection>​

Creates a secondary index.

Definition styles supported by the real handler:

  • --field <field> for a single-field index
  • --fields <json> for a JSON array of compound field definitions
  • --definition <json> for a full driver-shaped definition
  • --file <path> for a file containing a full driver-shaped definition

Optional modifiers:

  • --name <name>
  • --unique
  • --sparse
  • --partial-filter <json>
  • --partial-filter-file <path>

Examples:

liorandb index create users --field email --name users_email_idx --unique
liorandb index create orders --fields "[{\"field\":\"status\",\"direction\":\"asc\"},{\"field\":\"createdAt\",\"direction\":\"desc\"}]"
liorandb index create events --field archivedAt --partial-filter "{\"archived\":true}"

liorandb index create-text <collection> <field>​

Creates a text index.

Supported options:

  • --db <database>
  • --normalize
  • --stopwords <json>
  • --stopwords-file <path>

Example:

liorandb index create-text articles title --normalize --stopwords "[\"the\",\"a\"]"

liorandb index drop <collection> <name>​

Drops an index by name.

Supported option:

  • --db <database>

Human and machine output​

These same CRUD commands can be shaped for shell automation:

Automation-friendly output
liorandb find users --filter "{\"active\":true}" --output ndjson
liorandb find users --filter "{\"active\":true}" --json
liorandb insert-one users --json "{\"name\":\"Lin\"}" --quiet