zendb-cli

library0.4.1jsnpmunverified

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

database devops web-framework

npm install zendb-cli

github ↗package ↗

INSTALL

IMPORT

SIG · ZENDB-CLI

zendb-cli

databasejavascriptv0.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

zendb (CLI command)

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

✗ zendb import identity --dfx-identity <name>

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)

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

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

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

ZenDB.QueryBuilder

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

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

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

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

zendb --version

Debug

Known issues

gotchaIdentity 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.

affects: >=0.4.0

breakingThe 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'.

affects: >=0.4.0

gotchaCanister 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'.

affects: >=0.4.0

deprecatedThe '--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>)"

affects: >=0.4.0

gotchaDocument 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.

affects: >=0.4.0

Errors

Common errors & fixes

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

Canister not registered in local registry.

fix

Register the canister: zendb canister add <name> <canister-id> --ic

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

No identity cached; CLI needs an identity to authenticate.

fix

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

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

Document doesn't match collection schema.

fix

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

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

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

fix

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

Upgrade

Version history

0.4.1latest on npm

Audit

Dependencies

@zendb/corerequiredCore ZenDB library for Internet Computer integration

@dfinity/agentrequiredInternet Computer agent for interfacing with the blockchain

keytaroptionalOS-level keychain access for secure identity storage

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/NatLabs/zendb-platform ↗

packagehttps://www.npmjs.com/package/zendb-cli ↗