CLI
El comando namidb gestiona tu organización (bases de datos y clones, API
keys, tokens de gestión, backups, restauraciones incluidas las de un punto en
el tiempo, exportaciones, uso, miembros e invitaciones) y trabaja con tus
datos: consultas sueltas, un shell interactivo, importación de archivos y las
sentencias que se están ejecutando en una base de datos. Node.js 20 o
posterior.
npm install -g @namidb/clinamidb --helpLa herramienta de línea de comandos que viene con el motor open source es un programa distinto: consulta CLI (self-hosted).
Iniciar sesión
La CLI usa las mismas dos credenciales que las APIs:
| La usan | Dónde obtenerla | |
|---|---|---|
Token de gestión nmdb_mgmt_… | databases, clones, keys, tokens, backups, restores, exports, usage, members, invitations, orgs | Consola → Settings → Management API, o namidb tokens create |
API key nmdb_live_… | query, shell, schema, import, queries | Consola → API keys, o 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 guarda una API key que ya tienes; en scripts, pasa el
secreto por la entrada estándar: namidb login --with-token < token.txt. Los
secretos nunca se aceptan como flags, porque los flags terminan en el historial
del shell y en las listas de procesos.
Las credenciales se guardan en config.json (modo 0600, en un directorio
0700) dentro del directorio de configuración de tu usuario:
~/.config/namidb en Linux, ~/Library/Application Support/namidb en macOS,
%APPDATA%\namidb en Windows. NAMIDB_CONFIG_DIR lo reemplaza.
Perfiles
Un token de gestión pertenece a una organización, así que cada organización tiene un perfil:
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 olvida un perfil (--api-key solo su API key, --all todos los
perfiles). Cerrar sesión no revoca nada.
Variables de entorno
Tienen prioridad sobre el perfil, así que CI no necesita iniciar sesión:
| Variable | |
|---|---|
NAMIDB_MANAGEMENT_TOKEN | Token de gestión |
NAMIDB_API_KEY | API key para query, shell, schema, import, queries |
NAMIDB_PROFILE | Perfil a usar (--profile tiene prioridad) |
NAMIDB_MANAGEMENT_URL | Por defecto https://app.namidb.com/api/v1 |
NAMIDB_URL | Por defecto https://db.namidb.com |
NAMIDB_CONFIG_DIR | Dónde viven config.json y el historial del shell |
Comandos
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> --helpdescribe cada uno. Formas cortas:dbparadatabases,lsparalist,rmparadelete/revoke.--jsonimprime el JSON propio de la API (snake_case, como en la API de gestión). Las notas y el progreso van a stderr, así stdout queda limpio para usar en pipes.- Los comandos destructivos (
databases delete,keys revoke,tokens revoke,members remove) te piden que vuelvas a escribir el nombre; fuera de una terminal se niegan salvo que pases--yes. --waitconsulta un backup, una restauración, un clon, una exportación o una base de datos nueva hasta que termina, durante como máximo--timeout(30mpor defecto).
Las IP allowlists y los tickets de soporte todavía no están en la CLI: usa la API de gestión o los SDKs.
Clones y restauraciones a un punto en el tiempo
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 agoAmbos siempre crean una base de datos nueva. --at acepta un momento ISO 8601
(UTC salvo que indique una zona horaria) o cuánto tiempo atrás (90m, 6h,
2d, 1w). Dentro de la ventana de puntos de restauración del plan (Pro 48
horas, Scale 7 días) la base de datos nueva contiene exactamente ese momento;
antes de ella, o en Free, se copia el backup más reciente en ese momento o
antes. namidb clones get <id> muestra el punto de recuperación (vacío hasta
que existe la copia) y si lo sirvió un punto de restauración o un backup. Ver
Backups y restauración.
Tokens de gestión
namidb tokens create --name ci-deploy --scope write --expires-in 1d # prints the secret once, on stdoutnamidb tokens listnamidb tokens revoke <id>Requieren un token con el scope admin. Un token creado así actúa por la misma
persona que el token que estás usando, nunca tiene un scope más amplio y nunca
dura más que él; revocar un token revoca los que creó. En tokens list, *
marca el token que usa la CLI; revocarlo cierra la sesión de este perfil en su
siguiente petición.
Consultas en ejecución
namidb queries list movies # id, protocol, how long, statementnamidb queries cancel movies 42 43 # exit code 1 if one of them had already finishedAmbos usan una API key de lectura y escritura, porque las sentencias incluyen sus literales.
Consultas
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 moviesUn valor de --param se lee como JSON cuando se puede parsear (10, true,
["a","b"]) y como string en caso contrario. Las escrituras no se reintentan
después de un fallo ambiguo; pasa --idempotent para escrituras que se pueden
repetir sin problema.
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 peopleComandos del shell: :use <db>, :schema, :format table|json|jsonl|csv,
:param <name> <json>, :params (:params clear), :help, :exit. Ctrl-C
borra la sentencia, Ctrl-D sale. El historial se guarda junto a config.json
(modo 0600, sin las líneas :param; --no-history lo desactiva). Con stdin
redirigido, el shell ejecuta un script y se detiene en el primer error con
código de salida 1:
namidb shell movies < seed.cypherImportar
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 con una fila de encabezado, un array JSON de objetos, o JSON Lines
(.jsonl, .ndjson). Con --key, los nodos se fusionan (merge) sobre esa
propiedad; las relaciones se fusionan entre nodos existentes encontrados por
clave (--create crea todas las filas en su lugar). Los valores CSV son
strings salvo que pases --infer-types; los campos vacíos se omiten. Las filas
van en lotes (--batch-rows, 1000 por defecto) que esperan cuando hay límites
de uso. --dry-run revisa un archivo sin enviar nada.
Autocompletado del shell
source <(namidb completion bash) # in ~/.bashrcsource <(namidb completion zsh) # in ~/.zshrcnamidb completion fish > ~/.config/fish/completions/namidb.fishEl autocompletado cubre comandos y opciones, y los nombres de bases de datos obtenidos con tus credenciales.
Códigos de salida
| Código | |
|---|---|
| 0 | Éxito |
| 1 | La API rechazó o falló, o un --wait falló o superó el tiempo (stderr tiene el código de error y el id de petición) |
| 2 | Error de uso |
| 130 | Cancelado en una pregunta interactiva |