Skip to content

CLI

The namidb command manages your organization (databases and clones, API keys, management tokens, backups, restores including point in time, exports, usage, members and invitations) and works with your data: one-off queries, an interactive shell, file imports, and the statements running on a database. Node.js 20 or later.

Terminal window
npm install -g @namidb/cli
namidb --help

The command-line tool that ships with the open-source engine is a different program: see CLI (self-hosted).

Log in

The CLI uses the same two credentials as the APIs:

Used byWhere to get it
Management token nmdb_mgmt_…databases, clones, keys, tokens, backups, restores, exports, usage, members, invitations, orgsConsole → Settings → Management API, or namidb tokens create
API key nmdb_live_…query, shell, schema, import, queriesConsole → API keys, or namidb keys create --save
Terminal window
namidb login # paste the management token (not echoed)
namidb keys create --name laptop --save # create an API key and keep it for queries
namidb whoami

namidb login --api-key saves an API key you already have; in scripts, pipe the secret in: namidb login --with-token < token.txt. Secrets are never accepted as flags, because flags end up in shell history and process lists.

Credentials are saved in config.json (mode 0600, in a 0700 directory) in your user config directory: ~/.config/namidb on Linux, ~/Library/Application Support/namidb on macOS, %APPDATA%\namidb on Windows. NAMIDB_CONFIG_DIR overrides it.

Profiles

A management token belongs to one organization, so each organization gets a profile:

Terminal window
namidb login --profile acme-staging
namidb orgs list # profiles, the current one marked *
namidb orgs switch acme # by profile name or organization slug
namidb databases list --profile acme-staging

namidb logout forgets a profile (--api-key only its API key, --all every profile). Logging out revokes nothing.

Environment variables

They take precedence over the profile, so CI needs no login:

Variable
NAMIDB_MANAGEMENT_TOKENManagement token
NAMIDB_API_KEYAPI key for query, shell, schema, import, queries
NAMIDB_PROFILEProfile to use (--profile wins)
NAMIDB_MANAGEMENT_URLDefault https://app.namidb.com/api/v1
NAMIDB_URLDefault https://db.namidb.com
NAMIDB_CONFIG_DIRWhere config.json and the shell history live

Commands

namidb login | logout | whoami
namidb orgs show | list | switch <profile-or-slug>
namidb databases list | create <name> [--wait] | get <name> | delete <name> [--yes]
namidb databases clone <db> <new-database> [--source latest_backup|fresh_snapshot] [--at <time>] [--wait]
namidb clones get <id>
namidb keys list [--active] | create --name <n> [--role read-only] [--database <db>]… [--expires-in 90d] [--save]
namidb keys get <id> | rotate <id> [--overlap-days 1|7|30] [--save] | revoke <id> [--yes]
namidb tokens list [--active] | create --name <n> [--scope read|write|admin] [--expires-in 1d] | get <id> | revoke <id> [--yes]
namidb backups list <db> | create <db> [--wait] | get <id>
namidb restores create <backup-id> <new-database> [--wait] | get <id>
namidb restores create <db> <new-database> --at <time> [--wait]
namidb exports list <db> | create <db> [--wait] | get <id> | download <id> <file>
namidb usage
namidb members list | remove <user-id-or-email> [--yes]
namidb invitations list | create <email> [--role admin] | revoke <id>
namidb query <db> '<cypher>' [--param name=value]… [--params '{…}'] [--format table|json|jsonl|csv] [-f file]
namidb shell [db]
namidb schema <db>
namidb queries list <db> | cancel <db> <query-id>…
namidb import <db> <file> --label <Label> [--key <prop>]
namidb import <db> <file> --type <TYPE> --from <Label.key> --to <Label.key>
namidb completion bash|zsh|fish
namidb version
  • namidb <command> --help describes each one. Short forms: db for databases, ls for list, rm for delete / revoke.
  • --json prints the API’s own JSON (snake_case, as in the management API). Notes and progress go to stderr, so stdout stays clean for pipes.
  • Destructive commands (databases delete, keys revoke, tokens revoke, members remove) ask you to type the name back; outside a terminal they refuse unless you pass --yes.
  • --wait polls a backup, restore, clone, export or new database until it finishes, for at most --timeout (default 30m).

IP allowlists and support tickets are not in the CLI yet: use the management API or the SDKs.

Clones and point-in-time restores

Terminal window
namidb databases clone movies movies-staging --source fresh_snapshot --wait # back it up now, copy that
namidb databases clone movies movies-copy # from its latest backup
namidb restores create movies movies-tuesday --at 2026-11-03T09:00:00Z # as it was then
namidb restores create movies movies-before-import --at 2h --wait # two hours ago

Both always create a new database. --at takes an ISO 8601 time (UTC unless it names a time zone) or how long ago (90m, 6h, 2d, 1w). Inside the plan’s restore-point window (Pro 48 hours, Scale 7 days) the new database holds exactly that moment; before it, or on Free, the newest backup at or before it is copied. namidb clones get <id> shows the recovery point (empty until the copy exists) and whether a restore point or a backup served it. See Backups and restores.

Management tokens

Terminal window
namidb tokens create --name ci-deploy --scope write --expires-in 1d # prints the secret once, on stdout
namidb tokens list
namidb tokens revoke <id>

These need a token with the admin scope. A token created this way acts for the same person as the token you are using, is never broader in scope and never outlives it; revoking a token revokes the ones it created. * in tokens list marks the token the CLI is using; revoking it logs this profile out on its next request.

Running queries

Terminal window
namidb queries list movies # id, protocol, how long, statement
namidb queries cancel movies 42 43 # exit code 1 if one of them had already finished

Both use a read-write API key, since the statements include their literals.

Queries

Terminal window
namidb query movies 'MATCH (m:Movie) RETURN m.title AS title, m.released AS year LIMIT 5'
namidb query movies 'MATCH (m:Movie {released: $year}) RETURN count(m) AS n' --param year=1999
namidb query movies -f report.cypher --format csv > report.csv
echo 'MATCH (n) RETURN count(n)' | namidb query movies

A --param value is read as JSON when it parses (10, true, ["a","b"]) and as a string otherwise. Writes are not retried after an ambiguous failure; pass --idempotent for writes that are safe to repeat.

Shell

$ namidb shell movies
Connected to movies. Statements end with ;. Type :help for help, :exit to quit.
movies> MATCH (m:Movie)
| RETURN m.title AS title LIMIT 2;
TITLE
The Matrix
Heat
2 rows (4 ms)
movies> :param year 1999
movies> :use people

Shell commands: :use <db>, :schema, :format table|json|jsonl|csv, :param <name> <json>, :params (:params clear), :help, :exit. Ctrl-C clears the statement, Ctrl-D quits. History is kept next to config.json (mode 0600, :param lines excluded; --no-history turns it off). With stdin redirected the shell runs a script and stops at the first error with exit code 1:

Terminal window
namidb shell movies < seed.cypher

Import

Terminal window
namidb import movies people.csv --label Person --key id
namidb import movies acted_in.jsonl --type ACTED_IN --from Person.id --to Movie.id \
--from-field person --to-field movie

CSV with a header row, a JSON array of objects, or JSON Lines (.jsonl, .ndjson). With --key, nodes are merged on that property; relationships are merged between existing nodes found by key (--create creates every row instead). CSV values are strings unless you pass --infer-types; empty fields are skipped. Rows go in batches (--batch-rows, default 1000) that wait out rate limits. --dry-run checks a file without sending anything.

Shell completion

Terminal window
source <(namidb completion bash) # in ~/.bashrc
source <(namidb completion zsh) # in ~/.zshrc
namidb completion fish > ~/.config/fish/completions/namidb.fish

Completion covers commands and options, and database names fetched with your credentials.

Exit codes

Code
0Success
1The API refused or failed, or a --wait failed or timed out (stderr has the error code and request id)
2Usage error
130Cancelled at a prompt