Saltearse al contenido

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.

Ventana de terminal
npm install -g @namidb/cli
namidb --help

La 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 usanDónde obtenerla
Token de gestión nmdb_mgmt_…databases, clones, keys, tokens, backups, restores, exports, usage, members, invitations, orgsConsola → Settings → Management API, o namidb tokens create
API key nmdb_live_…query, shell, schema, import, queriesConsola → API keys, o namidb keys create --save
Ventana de terminal
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 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:

Ventana de terminal
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 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_TOKENToken de gestión
NAMIDB_API_KEYAPI key para query, shell, schema, import, queries
NAMIDB_PROFILEPerfil a usar (--profile tiene prioridad)
NAMIDB_MANAGEMENT_URLPor defecto https://app.namidb.com/api/v1
NAMIDB_URLPor defecto https://db.namidb.com
NAMIDB_CONFIG_DIRDónde viven config.json y el historial del shell

Comandos

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 describe cada uno. Formas cortas: db para databases, ls para list, rm para delete / revoke.
  • --json imprime 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.
  • --wait consulta un backup, una restauración, un clon, una exportación o una base de datos nueva hasta que termina, durante como máximo --timeout (30m por 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

Ventana de terminal
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

Ambos 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

Ventana de terminal
namidb tokens create --name ci-deploy --scope write --expires-in 1d # prints the secret once, on stdout
namidb tokens list
namidb 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

Ventana de terminal
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

Ambos usan una API key de lectura y escritura, porque las sentencias incluyen sus literales.

Consultas

Ventana de terminal
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

Un 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 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

Comandos 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:

Ventana de terminal
namidb shell movies < seed.cypher

Importar

Ventana de terminal
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 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

Ventana de terminal
source <(namidb completion bash) # in ~/.bashrc
source <(namidb completion zsh) # in ~/.zshrc
namidb completion fish > ~/.config/fish/completions/namidb.fish

El autocompletado cubre comandos y opciones, y los nombres de bases de datos obtenidos con tus credenciales.

Códigos de salida

Código
0Éxito
1La 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)
2Error de uso
130Cancelado en una pregunta interactiva