{"id":26682,"library":"zendb-cli","title":"ZenDB CLI","description":"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","status":"active","version":"0.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/NatLabs/zendb-platform","tags":["javascript","zendb","icp","internet-computer","database","cli","typescript"],"install":[{"cmd":"npm install zendb-cli","lang":"bash","label":"npm"},{"cmd":"yarn add zendb-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add zendb-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core ZenDB library for Internet Computer integration","package":"@zendb/core","optional":false},{"reason":"Internet Computer agent for interfacing with the blockchain","package":"@dfinity/agent","optional":false},{"reason":"OS-level keychain access for secure identity storage","package":"keytar","optional":true}],"imports":[{"note":"The CLI is invoked as a global command; no JavaScript import is used. Common mistakes include using incorrect subcommand names or flags.","wrong":"zendb import identity --dfx-identity <name>","symbol":"zendb (CLI command)","correct":"zendb user import --data \"$(dfx identity export <identity-name>)\" --mode keyring"},{"note":"Requires canister-id as string; wrong import path or missing parameter.","wrong":"import ZenDB \"zendb\";\nlet client = ZenDB.Client();","symbol":"ZenDB.Client (Motoko)","correct":"import ZenDB \"mo:zendb\";\nlet zendb_client = ZenDB.Client(\"<canister-id>\");"},{"note":"Uses fluent API with candid types; wrong method chaining or filter operators.","wrong":"let query = QueryBuilder().addFilter(\"name\", \"Alice\")","symbol":"ZenDB.QueryBuilder","correct":"let query = ZenDB.QueryBuilder()\n  .Where(\"name\", #eq(#Text(\"Alice\")))\n  .And(\"age\", #gt(#Nat(25)));"}],"quickstart":{"code":"npm install -g @zendb/cli\n\n# Import identity from dfx\nzendb user import --mode keyring --data \"$(dfx identity export default)\"\nzendb user get-principal\n\n# Create a canister and database\nzendb canister create myapp --ic --release latest\nzendb db create myapp --canister myapp\n\n# Create a collection and insert documents\nzendb collection create users --canister myapp --db myapp --schema 'record { name: text; age: nat }'\nzendb document insert --canister myapp --db myapp --collection users --data '{\"name\":\"Alice\",\"age\":30}'\nzendb document list --canister myapp --db myapp --collection users --limit 10\n\n# Query\nzendb document search --canister myapp --db myapp --collection users\n\n# View stats\nzendb canister stats myapp\nzendb database stats myapp --canister myapp","lang":"shell","description":"Full workflow: install CLI, import identity, create canister & database, add collection, insert/list/search documents, and view stats."},"warnings":[{"fix":"Use --mode keyring for secure keychain storage, or --mode password and provide a passphrase.","message":"Identity storage options: 'keyring' uses OS keychain, 'password' asks for passphrase. Default is 'password' if not specified.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Replace 'zendb identity import' with 'zendb user import', and 'zendb identity get-principal' with 'zendb user get-principal'.","message":"The CLI v0.4.0 renamed 'zendb identity' commands to 'zendb user'.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Use '--release v2.0' or similar specific version instead of 'latest'.","message":"Canister create with --release flag: Using 'latest' may break if API changes. Pin to a specific version for production.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Use 'zendb user import --mode keyring --data \"$(dfx identity export <name>)\"","message":"The '--data' flag for user import accepts PEM or string; using dfx export directly is preferred over PEM files.","severity":"deprecated","affected_versions":">=0.4.0"},{"fix":"Use '--data @./users.json' instead of inline JSON for large payloads.","message":"Document insert with --data flag: For large data sets, use '@./file.json' to avoid shell quoting issues.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Register the canister: zendb canister add <name> <canister-id> --ic","cause":"Canister not registered in local registry.","error":"Error: Canister not found. Use 'zendb canister add' to register it."},{"fix":"Run 'zendb user import --mode keyring --data \"$(dfx identity export default)\"'","cause":"No identity cached; CLI needs an identity to authenticate.","error":"Error: No identity found. Import an identity first with 'zendb user import'."},{"fix":"Ensure inserted documents match the schema definition. Use --schema flag to define exact record shape.","cause":"Document doesn't match collection schema.","error":"Error: Schema validation failed: expected record { name: text; age: nat } but got record { name: text }"},{"fix":"Assign appropriate role: zendb role assign <role> --principal <principal> --canister <name> --db <db>","cause":"Identity lacks permission to perform action on canister/database/collection.","error":"Error: Not authorized. Ensure your identity has the required role."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}