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
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 defectodefault) 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.
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:
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/3constraint applied (manifest v1)== statement 2/3────────────────────────────────────────────────nodes created : 1edges created : 0nodes deleted : 0edges deleted : 0properties set : 0returned 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:
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.
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| Flag | Efecto |
|---|---|
-v, --verbose | Anota cada operador con su cantidad estimada de filas (igual que el prefijo EXPLAIN VERBOSE). |
--raw | Omite 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:
namidb parse "match (a:Person) where a.age>1 return a.name"# MATCH (a:Person) WHERE (a.age > 1) RETURN a.namenamespace-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:
namidb namespace-check acme-prod # ok: acme-prodnamidb namespace-check Bad # Error: … must start with [a-z0-9] (exit 1)backup, restore y restore-points
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.
namidb backup --from "s3://bucket?ns=prod" --to "file:///snapshots/prod?ns=prod" --verifybacked up s3://bucket?ns=prod (source version 5) -> file:///snapshots/prod?ns=prod 5 objects, 1122 bytesrestore 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.
| Flag | Efecto |
|---|---|
--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. |
--force | Sobrescribe un destino que ya contiene un namespace. |
--verify | Vuelve 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:
namidb load-vault --store "file:///var/lib/namidb?ns=vault" --embed ./my-vault────────────────────────────────────────────────notes loaded : 2links resolved : 2links dangling : 0embeds resolved : 0embeds dangling : 1name collisions : 0tags loaded : 2tag links : 2subtag edges : 1────────────────────────────────────────────────| Flag | Por defecto | Efecto |
|---|---|---|
--store <URI> | en memoria | Dónde escribir el grafo. Sin él, la carga solo informa los conteos. |
-n, --namespace | default | Nombre del namespace cuando se omite --store. |
--label | Note | Label para los nodos de notas. |
--edge-type | LINKS_TO | Tipo de relación para los wikilinks. |
--prune | desactivado | Refleja el vault: marca como borradas (tombstone) las notas y los links que desaparecieron desde la última carga. |
--placeholders | desactivado | Crea nodos :Note stub (placeholder: true) para los links cuyo destino no existe. |
--embed | desactivado | Guarda un embedding por nota para búsqueda vectorial, con un embedder local, determinista y sin conexión. |
--watch | desactivado | Sigue observando la carpeta y vuelve a sincronizar con cada cambio hasta que se interrumpa. Implica --prune. |
Qué se convierte en qué:
| Markdown | Grafo |
|---|---|
Un archivo .md | Nodo :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 frontmatter | Nodo :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.
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:
cargo install --locked --path crates/namidb-cli --features namidb-markdown/remote-embeddery configúralo con variables de entorno:
| Variable | Significado |
|---|---|
NAMIDB_EMBEDDER=remote | Obligatoria para cambiar del embedder local a un proveedor remoto. |
NAMIDB_EMBED_PROVIDER | openai (por defecto), voyage, cohere, gemini o jina. |
NAMIDB_EMBED_MODEL | Nombre del modelo. Valores por defecto: text-embedding-3-large, voyage-4-large, embed-v4.0, gemini-embedding-001, jina-embeddings-v4. |
NAMIDB_EMBED_DIM | Dimensión de salida, por defecto 1024. |
NAMIDB_EMBED_API_KEY | API 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_URL | Reemplaza 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
namidb version# namidb 3.3.0