CLI
namidb is a single binary with no daemon. It opens a namespace, does one
job, and exits. Get it from the namidb-v3.3.0-<target> release archive or
build it with cargo install --locked --path crates/namidb-cli (see
Install).
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`The CLI logs at info level by default (cache sizing, for example). Set
RUST_LOG=warn to keep only results on screen.
run
namidb run [--store <URI>] [-n <NAMESPACE>] "<cypher>"- Without
--store, the statement runs against an ephemeral in-memory namespace (named by-n, defaultdefault) that vanishes on exit. - With
--store, the namespace is durable on that backend; the URI carries its own?ns=. See Storage URIs. - Reads print a table; writes print the write counters.
namidb run --store "file:///var/lib/namidb?ns=prod" \ "MATCH (p:Person) RETURN p.name AS name ORDER BY name"name--------"Ada""Grace"Scripts. The argument may hold several statements separated by ;.
Semicolons inside strings, backtick identifiers and comments do not split.
Statements run in order against one session and stop at the first error;
CREATE CONSTRAINT / CREATE INDEX run as schema commands, so a pasted
schema-bootstrap script works:
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 inside run renders the plan with the namespace’s real
statistics and the physical route chosen for indexed lookups, without
executing:
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
Plans a query offline (no store, empty statistics) and prints the optimised logical plan.
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 | Effect |
|---|---|
-v, --verbose | Annotate each operator with its estimated row count (same as an EXPLAIN VERBOSE prefix). |
--raw | Skip the optimizer and print the plan exactly as lowered (same as EXPLAIN RAW). |
parse
Prints the canonical form of a query, which is handy for checking how an expression was understood:
namidb parse "match (a:Person) where a.age>1 return a.name"# MATCH (a:Person) WHERE (a.age > 1) RETURN a.namenamespace-check
Validates a namespace name ([a-z0-9][a-z0-9_-]{0,62}). Exits non-zero on
an invalid name, so it fits in provisioning scripts:
namidb namespace-check acme-prod # ok: acme-prodnamidb namespace-check Bad # Error: … must start with [a-z0-9] (exit 1)backup, restore and 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 pins a manifest version and copies its closure (manifest, data
files and side-cars, and the WAL segments still needed for recovery) to a
fresh location, leaving a self-contained namespace there. It is safe against
a live source: the pinned version is protected by a retention lease that the
server’s janitor honours.
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 is the same copy in the other direction. The destination must be
offline (nothing fences a concurrent writer) and must not already hold a
namespace unless you pass --force.
| Flag | Effect |
|---|---|
--version <N> | Copy that manifest version instead of the current one. |
--as-of <instant> | backup only: copy the namespace as it was at this RFC 3339 instant (the newest version committed at or before it). It must fall inside the source’s restore point window. |
--force | Overwrite a destination that already holds a namespace. |
--verify | Re-open the destination and check every referenced object exists and is non-empty. |
restore-points prints a namespace’s restore point window and its newest
points (20 by default, --limit): the instants backup --as-of can copy. A
namespace keeps that history only when a server runs on it with
--restore-point-retention; otherwise the window is the current version.
$ 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 …Full procedures, including the server’s online backup endpoint, restore points and multi-tenant restores, are in Backup and restore.
load-vault
Turns a folder of Markdown notes (an Obsidian vault, for example) into a graph:
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 | Default | Effect |
|---|---|---|
--store <URI> | in-memory | Where to write the graph. Without it the load only reports counts. |
-n, --namespace | default | Namespace name when --store is omitted. |
--label | Note | Label for note nodes. |
--edge-type | LINKS_TO | Edge type for wikilinks. |
--prune | off | Mirror the vault: tombstone notes and links that disappeared since the last load. |
--placeholders | off | Create stub :Note nodes (placeholder: true) for links whose target does not exist. |
--embed | off | Store an embedding per note for vector search, using a local, deterministic, offline embedder. |
--watch | off | Keep watching the folder and re-sync on every change until interrupted. Implies --prune. |
What becomes what:
| Markdown | Graph |
|---|---|
A .md file | :Note node with title, path, key, body, content_hash and frontmatter keys as properties |
[[wikilink]], [[a|alias]], [[a#heading]], [text](note.md) | :LINKS_TO edge |
![[embed]] | :EMBEDS edge |
#tag, frontmatter tags: | :Tag node and a :TAGGED edge |
Nested tag #area/db | :Tag {name: 'area/db'} with a :SUBTAG_OF edge to area |
Names resolve by normalised basename (case, -, _ and spaces are
ignored; common Latin diacritics fold), and frontmatter aliases register
alternate names.
namidb run --store "file:///var/lib/namidb?ns=vault" \ "MATCH (n:Note {title: 'Project X'})<-[:LINKS_TO]-(m:Note) RETURN m.title"Remote embeddings. The built-in embedder is fast and offline but not semantic. For real semantic quality, build the CLI from source with the remote embedder:
cargo install --locked --path crates/namidb-cli --features namidb-markdown/remote-embedderand configure it with environment variables:
| Variable | Meaning |
|---|---|
NAMIDB_EMBEDDER=remote | Required to switch from the local embedder to a remote provider. |
NAMIDB_EMBED_PROVIDER | openai (default), voyage, cohere, gemini or jina. |
NAMIDB_EMBED_MODEL | Model name. Defaults: text-embedding-3-large, voyage-4-large, embed-v4.0, gemini-embedding-001, jina-embeddings-v4. |
NAMIDB_EMBED_DIM | Output dimension, default 1024. |
NAMIDB_EMBED_API_KEY | API key. Falls back to the provider’s own variable: OPENAI_API_KEY, VOYAGE_API_KEY, CO_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY, JINA_API_KEY. |
NAMIDB_EMBED_URL | Override the provider endpoint (for a proxy or compatible gateway). |
To serve a vault to an AI agent, see the MCP server.
version
namidb version# namidb 3.3.0