ZenDB CLI

0.4.1 verified Fri May 01 auth: no javascript

ZenDB CLI (v0.4.1, Alpha) is a command-line interface for interacting with ZenDB, a document database built for the Internet Computer (ICP). It enables developers to manage identities, canisters, databases, collections, documents, indexes, and roles directly from the terminal. Key differentiators include native integration with Internet Identity and dfx, secure keychain-backed identity storage, support for Motoko typed collections, and commands for both local development and mainnet deployment. The CLI uses encrypted storage and OS keychain for security. Note: The package is in early alpha; APIs may change. GitHub: https://github.com/NatLabs/zendb-platform

Common errors

error Error: Canister not found. Use 'zendb canister add' to register it. ↓

cause Canister not registered in local registry.

fix

error Error: No identity found. Import an identity first with 'zendb user import'. ↓

cause No identity cached; CLI needs an identity to authenticate.

fix

Run 'zendb user import --mode keyring --data "$(dfx identity export default)"'

error Error: Schema validation failed: expected record { name: text; age: nat } but got record { name: text } ↓

cause Document doesn't match collection schema.

fix

Ensure inserted documents match the schema definition. Use --schema flag to define exact record shape.

error Error: Not authorized. Ensure your identity has the required role. ↓

cause Identity lacks permission to perform action on canister/database/collection.

fix

Assign appropriate role: zendb role assign <role> --principal <principal> --canister <name> --db <db>

Warnings

gotcha Identity storage options: 'keyring' uses OS keychain, 'password' asks for passphrase. Default is 'password' if not specified. ↓

fix Use --mode keyring for secure keychain storage, or --mode password and provide a passphrase.

breaking The CLI v0.4.0 renamed 'zendb identity' commands to 'zendb user'. ↓

fix Replace 'zendb identity import' with 'zendb user import', and 'zendb identity get-principal' with 'zendb user get-principal'.

gotcha Canister create with --release flag: Using 'latest' may break if API changes. Pin to a specific version for production. ↓

fix Use '--release v2.0' or similar specific version instead of 'latest'.

deprecated The '--data' flag for user import accepts PEM or string; using dfx export directly is preferred over PEM files. ↓

fix Use 'zendb user import --mode keyring --data "$(dfx identity export <name>)"

gotcha Document insert with --data flag: For large data sets, use '@./file.json' to avoid shell quoting issues. ↓

fix Use '--data @./users.json' instead of inline JSON for large payloads.

Install

npm install zendb-cli

yarn add zendb-cli

pnpm add zendb-cli

Imports

zendb (CLI command)
wrong
```
zendb import identity --dfx-identity <name>
```
correct
```
zendb user import --data "$(dfx identity export <identity-name>)" --mode keyring
```
The CLI is invoked as a global command; no JavaScript import is used. Common mistakes include using incorrect subcommand names or flags.

ZenDB.Client (Motoko)

wrong

import ZenDB "zendb";
let client = ZenDB.Client();

correct

import ZenDB "mo:zendb";
let zendb_client = ZenDB.Client("<canister-id>");

Requires canister-id as string; wrong import path or missing parameter.

ZenDB.QueryBuilder

wrong

let query = QueryBuilder().addFilter("name", "Alice")

correct

let query = ZenDB.QueryBuilder()
  .Where("name", #eq(#Text("Alice")))
  .And("age", #gt(#Nat(25)));

Uses fluent API with candid types; wrong method chaining or filter operators.

Quickstart

Full workflow: install CLI, import identity, create canister & database, add collection, insert/list/search documents, and view stats.

npm install -g @zendb/cli

# Import identity from dfx
zendb user import --mode keyring --data "$(dfx identity export default)"
zendb user get-principal

# Create a canister and database
zendb canister create myapp --ic --release latest
zendb db create myapp --canister myapp

# Create a collection and insert documents
zendb collection create users --canister myapp --db myapp --schema 'record { name: text; age: nat }'
zendb document insert --canister myapp --db myapp --collection users --data '{"name":"Alice","age":30}'
zendb document list --canister myapp --db myapp --collection users --limit 10

# Query
zendb document search --canister myapp --db myapp --collection users

# View stats
zendb canister stats myapp
zendb database stats myapp --canister myapp