ZenDB CLI

Command-line interface for ZenDB on the Internet Computer.

Install

npm install -g @zendb/cli

Or install locally:

cd cli
npm install
npm run build
npm link

Quick Start

1. Import Identity

Import your Internet Identity (or dfx identity) into encrypted storage. The CLI uses OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) for secure key storage:

# Export your identity from dfx and import into zendb
zendb user import --data "$(dfx identity export <identity-name>)" --mode keyring

# Or import a PEM file directly
zendb user import --data "$(cat ~/path/to/identity.pem)" --mode password

Verify the identity:

zendb user get-principal
zendb user status

To clear the in-process identity cache:

zendb user lock

2. Add a Canister

Deploy a canister via the cli or add an existing canister to your local registry. The registry maps user friendly names to canister IDs.

• create

zendb canister create dev --ic --release latest
zendb canister create local-dev --local --release latest

zendb canister list

• add

zendb canister add dev qljpb-nqaaa-aaaaj-a2hha-cai --ic
zendb canister add local-dev <CANISTER_ID> --local

3. Create Database and Collection

zendb db create myapp --canister dev
zendb collection create users --canister dev --db myapp --schema 'record { name: text; age: nat }'

Omit --schema to launch the interactive schema builder.

4. Insert and Query

zendb document insert --canister dev --db myapp --collection users --data '{"name":"Alice","age":30}'
zendb document insert --canister dev --db myapp --collection users --data @./users.json
zendb document list --canister dev --db myapp --collection users --limit 10
zendb document search --canister dev --db myapp --collection users

5. Use ZenDB in Motoko

Import ZenDB in your canister code and create a typed collection client:

import Principal "mo:base/Principal";
import ZenDB "mo:zendb";

let zendb_client = ZenDB.Client("<canister-id>");
let db = zendb_client.getDB("myapp");

type User = { name : Text; age : Nat };
let candify : ZenDB.Types.Candify<User> = {
	from_blob = func(blob : Blob) : ?User = from_candid(blob);
	to_blob = func(value : User) : Blob = to_candid(value);
};

let users = db.getCollection<User>("users", candify);

let alice = { name = "Alice"; age = 30 };
let #ok(alice_id) = await users.insert(alice);

let #ok(response) = await users.search(
  ZenDB.QueryBuilder()
    .Where("name", #eq(#Text("Alice)))
    .And("age", #gt(#Nat(25)))
);

assert response.documents == [(alice_id, { name = "Alice"; age = 30 }, [])];
assert (await users.get(alice_id)) == alice;

6. View Canister Stats

zendb canister stats dev
zendb database stats myapp --canister dev
zendb collection stats users --db myapp --canister dev

Configuration

Configuration files are written under ~/.zendb/:

• config.json — Canister registry
• identity.vault.json — Encrypted identity storage (never plaintext)

Command Reference

zendb user ...
zendb canister ...
zendb db ...
zendb collection ...
zendb document ...
zendb index ...
zendb role ...
zendb release ...

Common Workflows

Index Management

zendb index create age_idx --canister dev --db myapp --collection users --fields age:asc
zendb index list --canister dev --db myapp --collection users
zendb index delete age_idx --canister dev --db myapp --collection users

Text indexes:

zendb index create-text search_idx --canister dev --db myapp --collection users --fields name,email
zendb index delete-text search_idx --canister dev --db myapp --collection users

Canister Lifecycle

zendb canister create local-dev --local --release latest
zendb canister status local-dev
zendb canister stats local-dev
zendb canister top-up local-dev 1T
zendb canister upgrade local-dev --release v2.0.0

Release cache:

zendb release list
zendb release pull v1.1.0
zendb release remove v1.1.0

Role Management

Scope is determined by flags. Use --global for canister-wide access (requires explicit flag), --db for database scope, or --db --collection for collection scope.

zendb role grant admin <principal> --global --canister dev
zendb role grant writer <principal> --db myapp --canister dev
zendb role grant reader <principal> --db myapp --collection users --canister dev
zendb role revoke writer <principal> --db myapp --canister dev
zendb role list --canister dev
zendb role list --all --canister dev

Development

npm install
npm run typecheck
npm run build
npm run dev

Publish Checklist

Before publishing to npm:

• [ ] npm run typecheck passes
• [ ] npm run build succeeds
• [ ] All CLI commands work: zendb user, zendb canister, zendb db, etc.
• [ ] Identity import with keyring/password modes works
• [ ] Keyring secrets are not persisted to disk (keyring mode only)
• [ ] Session TTL works for password mode (30 min default, expires safely)
• [ ] npm pack --dry-run shows correct files in dist/
• [ ] README is up-to-date with zendb binary name
• [ ] Version bumped in package.json
• [ ] Changelog updated if applicable
• [ ] Tested on macOS, Windows, Linux (if applicable)

Publish:

npm run typecheck
npm run build
npm publish

prepublishOnly runs typecheck and build automatically before publish.

Security Note

user import stores identity in encrypted vault storage at ~/.zendb/config/identity.vault.json. In keyring mode, encryption keys stay in the OS credential manager.

License

MIT