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.
npm install -g @namidb/clinamidb --helpThe 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 by | Where to get it | |
|---|---|---|
Management token nmdb_mgmt_… | databases, clones, keys, tokens, backups, restores, exports, usage, members, invitations, orgs | Console → Settings → Management API, or namidb tokens create |
API key nmdb_live_… | query, shell, schema, import, queries | Console → API keys, or namidb keys create --save |
namidb login # paste the management token (not echoed)namidb keys create --name laptop --save # create an API key and keep it for queriesnamidb whoaminamidb 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:
namidb login --profile acme-stagingnamidb orgs list # profiles, the current one marked *namidb orgs switch acme # by profile name or organization slugnamidb databases list --profile acme-stagingnamidb 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_TOKEN | Management token |
NAMIDB_API_KEY | API key for query, shell, schema, import, queries |
NAMIDB_PROFILE | Profile to use (--profile wins) |
NAMIDB_MANAGEMENT_URL | Default https://app.namidb.com/api/v1 |
NAMIDB_URL | Default https://db.namidb.com |
NAMIDB_CONFIG_DIR | Where config.json and the shell history live |
Commands
namidb login | logout | whoaminamidb 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 usagenamidb 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|fishnamidb versionnamidb <command> --helpdescribes each one. Short forms:dbfordatabases,lsforlist,rmfordelete/revoke.--jsonprints 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. --waitpolls a backup, restore, clone, export or new database until it finishes, for at most--timeout(default30m).
IP allowlists and support tickets are not in the CLI yet: use the management API or the SDKs.
Clones and point-in-time restores
namidb databases clone movies movies-staging --source fresh_snapshot --wait # back it up now, copy thatnamidb databases clone movies movies-copy # from its latest backupnamidb restores create movies movies-tuesday --at 2026-11-03T09:00:00Z # as it was thennamidb restores create movies movies-before-import --at 2h --wait # two hours agoBoth 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
namidb tokens create --name ci-deploy --scope write --expires-in 1d # prints the secret once, on stdoutnamidb tokens listnamidb 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
namidb queries list movies # id, protocol, how long, statementnamidb queries cancel movies 42 43 # exit code 1 if one of them had already finishedBoth use a read-write API key, since the statements include their literals.
Queries
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=1999namidb query movies -f report.cypher --format csv > report.csvecho 'MATCH (n) RETURN count(n)' | namidb query moviesA --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 moviesConnected to movies. Statements end with ;. Type :help for help, :exit to quit.movies> MATCH (m:Movie) | RETURN m.title AS title LIMIT 2;TITLEThe MatrixHeat2 rows (4 ms)movies> :param year 1999movies> :use peopleShell 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:
namidb shell movies < seed.cypherImport
namidb import movies people.csv --label Person --key idnamidb import movies acted_in.jsonl --type ACTED_IN --from Person.id --to Movie.id \ --from-field person --to-field movieCSV 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
source <(namidb completion bash) # in ~/.bashrcsource <(namidb completion zsh) # in ~/.zshrcnamidb completion fish > ~/.config/fish/completions/namidb.fishCompletion covers commands and options, and database names fetched with your credentials.
Exit codes
| Code | |
|---|---|
| 0 | Success |
| 1 | The API refused or failed, or a --wait failed or timed out (stderr has the error code and request id) |
| 2 | Usage error |
| 130 | Cancelled at a prompt |