Saltearse al contenido

CLI

namidb es un único binario sin daemon. Abre un namespace, hace un trabajo y termina. Obtenlo del archivo del release namidb-v3.3.0-<target> o compílalo con cargo install --locked --path crates/namidb-cli (consulta Instalación).

namidb <COMMAND>
Commands:
version Print build information
namespace-check Validate a namespace identifier
parse Parse a Cypher query and print the round-trip canonical form
explain Lower a Cypher query and print its logical plan tree
run Run a Cypher query (or a ;-separated script) against a namespace
load-vault Load an Obsidian-style Markdown vault as a graph
backup Copy a consistent snapshot of a namespace to another location
restore-points List a namespace's restore points: the versions `backup --as-of` can copy
restore Restore a namespace from a backup made with `backup`

La CLI registra logs en nivel info por defecto (el tamaño de las cachés, por ejemplo). Define RUST_LOG=warn para ver solo los resultados en pantalla.

run

Ventana de terminal
namidb run [--store <URI>] [-n <NAMESPACE>] "<cypher>"
  • Sin --store, la sentencia se ejecuta contra un namespace efímero en memoria (con el nombre indicado por -n, por defecto default) que desaparece al salir.
  • Con --store, el namespace es durable en ese backend; el URI lleva su propio ?ns=. Consulta URIs de almacenamiento.
  • Las lecturas imprimen una tabla; las escrituras imprimen los contadores de escritura.
Ventana de terminal
namidb run --store "file:///var/lib/namidb?ns=prod" \
"MATCH (p:Person) RETURN p.name AS name ORDER BY name"
name
--------
"Ada"
"Grace"

Scripts. El argumento puede contener varias sentencias separadas por ;. Los puntos y coma dentro de strings, identificadores entre backticks y comentarios no separan. Las sentencias se ejecutan en orden contra una misma sesión y se detienen en el primer error; CREATE CONSTRAINT / CREATE INDEX se ejecutan como comandos de esquema, así que un script de inicialización del esquema pegado tal cual funciona:

Ventana de terminal
namidb run --store "file:///var/lib/namidb?ns=prod" "
CREATE CONSTRAINT person_id IF NOT EXISTS FOR (p:Person) REQUIRE p.id IS UNIQUE;
CREATE (:Person {id: 1, name: 'Ada'});
CREATE (:Person {id: 2, name: 'Grace'})
"
== statement 1/3
constraint applied (manifest v1)
== statement 2/3
────────────────────────────────────────────────
nodes created : 1
edges created : 0
nodes deleted : 0
edges deleted : 0
properties set : 0
returned rows : 0
────────────────────────────────────────────────
(no rows)
== statement 3/3
…

EXPLAIN dentro de run muestra el plan con las estadísticas reales del namespace y la ruta física elegida para las búsquedas por índice, sin ejecutar:

Ventana de terminal
namidb run --store "file:///var/lib/namidb?ns=prod" \
"EXPLAIN MATCH (p:Person {id: 1}) RETURN p"
Project [p=p]
NodeByPropertyValue label=Person alias=p id=1
Empty
# route: Person.id → memtable (unique lookup; no SSTs in scope)

explain

Planifica una consulta sin conexión (sin store, con estadísticas vacías) e imprime el plan lógico optimizado.

Ventana de terminal
namidb explain "MATCH (a:Person)-[:KNOWS]->(b) WHERE a.age > 30 RETURN b.name LIMIT 20"
Project [b.name=b.name]
TopN limit=20
Filter ((a.age > 30))
Expand source=a edge_type=KNOWS dir=-> target=b
NodeScan label=Person alias=a
FlagEfecto
-v, --verboseAnota cada operador con su cantidad estimada de filas (igual que el prefijo EXPLAIN VERBOSE).
--rawOmite el optimizador e imprime el plan exactamente como se generó (igual que EXPLAIN RAW).

parse

Imprime la forma canónica de una consulta, útil para comprobar cómo se interpretó una expresión:

Ventana de terminal
namidb parse "match (a:Person) where a.age>1 return a.name"
# MATCH (a:Person) WHERE (a.age > 1) RETURN a.name

namespace-check

Valida un nombre de namespace ([a-z0-9][a-z0-9_-]{0,62}). Termina con un código distinto de cero ante un nombre inválido, así que encaja en scripts de aprovisionamiento:

Ventana de terminal
namidb namespace-check acme-prod # ok: acme-prod
namidb namespace-check Bad # Error: … must start with [a-z0-9] (exit 1)

backup, restore y restore-points

Ventana de terminal
namidb backup --from <URI> --to <URI> [--version <N> | --as-of <instant>] [--force] [--verify]
namidb restore --from <URI> --to <URI> [--version <N>] [--force] [--verify]
namidb restore-points --from <URI> [--limit <N>]

backup fija una versión del manifest y copia su clausura (manifest, archivos de datos y side-cars, y los segmentos del WAL que todavía se necesitan para la recuperación) a una ubicación nueva, dejando ahí un namespace autocontenido. Es seguro contra un origen en vivo: la versión fijada queda protegida por un lease de retención que respeta el janitor del servidor.

Ventana de terminal
namidb backup --from "s3://bucket?ns=prod" --to "file:///snapshots/prod?ns=prod" --verify
backed up s3://bucket?ns=prod (source version 5) -> file:///snapshots/prod?ns=prod
5 objects, 1122 bytes

restore es la misma copia en la dirección contraria. El destino debe estar fuera de línea (nada bloquea a un writer concurrente) y no debe contener ya un namespace, salvo que pases --force.

FlagEfecto
--version <N>Copia esa versión del manifest en lugar de la actual.
--as-of <instante>Solo backup: copia el namespace tal como estaba en este instante RFC 3339 (la versión más reciente confirmada en ese instante o antes). Debe caer dentro de la ventana de puntos de restauración del origen.
--forceSobrescribe un destino que ya contiene un namespace.
--verifyVuelve a abrir el destino y comprueba que cada objeto referenciado existe y no está vacío.

restore-points imprime la ventana de puntos de restauración de un namespace y sus puntos más recientes (20 por defecto, --limit): los instantes que puede copiar backup --as-of. Un namespace conserva ese historial solo cuando un servidor se ejecuta sobre él con --restore-point-retention; si no, la ventana es la versión actual.

$ namidb restore-points --from "s3://bucket?ns=prod"
restore point window: retention 604800s, lease expires 2026-11-11T07:09:15+00:00
earliest v0 at 2026-11-04T06:54:15.675743809+00:00
latest v3 at 2026-11-04T06:54:22.754928510+00:00
v3 2026-11-04T06:54:22.754928510+00:00
v2 2026-11-04T06:54:19.725732876+00:00
…

Los procedimientos completos, incluidos el endpoint de backup en línea del servidor, los puntos de restauración y los restores multi-tenant, están en Backup y restore.

load-vault

Convierte una carpeta de notas Markdown (un vault de Obsidian, por ejemplo) en un grafo:

Ventana de terminal
namidb load-vault --store "file:///var/lib/namidb?ns=vault" --embed ./my-vault
────────────────────────────────────────────────
notes loaded : 2
links resolved : 2
links dangling : 0
embeds resolved : 0
embeds dangling : 1
name collisions : 0
tags loaded : 2
tag links : 2
subtag edges : 1
────────────────────────────────────────────────
FlagPor defectoEfecto
--store <URI>en memoriaDónde escribir el grafo. Sin él, la carga solo informa los conteos.
-n, --namespacedefaultNombre del namespace cuando se omite --store.
--labelNoteLabel para los nodos de notas.
--edge-typeLINKS_TOTipo de relación para los wikilinks.
--prunedesactivadoRefleja el vault: marca como borradas (tombstone) las notas y los links que desaparecieron desde la última carga.
--placeholdersdesactivadoCrea nodos :Note stub (placeholder: true) para los links cuyo destino no existe.
--embeddesactivadoGuarda un embedding por nota para búsqueda vectorial, con un embedder local, determinista y sin conexión.
--watchdesactivadoSigue observando la carpeta y vuelve a sincronizar con cada cambio hasta que se interrumpa. Implica --prune.

Qué se convierte en qué:

MarkdownGrafo
Un archivo .mdNodo :Note con title, path, key, body, content_hash y las claves del frontmatter como propiedades
[[wikilink]], [[a|alias]], [[a#heading]], [text](note.md)Relación :LINKS_TO
![[embed]]Relación :EMBEDS
#tag, tags: en el frontmatterNodo :Tag y una relación :TAGGED
Tag anidado #area/db:Tag {name: 'area/db'} con una relación :SUBTAG_OF hacia area

Los nombres se resuelven por el nombre base normalizado (se ignoran las mayúsculas, -, _ y los espacios; los diacríticos latinos comunes se normalizan), y los aliases del frontmatter registran nombres alternativos.

Ventana de terminal
namidb run --store "file:///var/lib/namidb?ns=vault" \
"MATCH (n:Note {title: 'Project X'})<-[:LINKS_TO]-(m:Note) RETURN m.title"

Embeddings remotos. El embedder integrado es rápido y funciona sin conexión, pero no es semántico. Para una calidad semántica real, compila la CLI desde el código fuente con el embedder remoto:

Ventana de terminal
cargo install --locked --path crates/namidb-cli --features namidb-markdown/remote-embedder

y configúralo con variables de entorno:

VariableSignificado
NAMIDB_EMBEDDER=remoteObligatoria para cambiar del embedder local a un proveedor remoto.
NAMIDB_EMBED_PROVIDERopenai (por defecto), voyage, cohere, gemini o jina.
NAMIDB_EMBED_MODELNombre del modelo. Valores por defecto: text-embedding-3-large, voyage-4-large, embed-v4.0, gemini-embedding-001, jina-embeddings-v4.
NAMIDB_EMBED_DIMDimensión de salida, por defecto 1024.
NAMIDB_EMBED_API_KEYAPI key. Si no está, usa la variable propia del proveedor: OPENAI_API_KEY, VOYAGE_API_KEY, CO_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY, JINA_API_KEY.
NAMIDB_EMBED_URLReemplaza el endpoint del proveedor (para un proxy o un gateway compatible).

Para servir un vault a un agente de IA, consulta el servidor MCP.

version

Ventana de terminal
namidb version
# namidb 3.3.0