Skip to content

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

Terminal window
namidb run [--store <URI>] [-n <NAMESPACE>] "<cypher>"
  • Without --store, the statement runs against an ephemeral in-memory namespace (named by -n, default default) 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.
Terminal window
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:

Terminal window
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 inside run renders the plan with the namespace’s real statistics and the physical route chosen for indexed lookups, without executing:

Terminal window
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.

Terminal window
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
FlagEffect
-v, --verboseAnnotate each operator with its estimated row count (same as an EXPLAIN VERBOSE prefix).
--rawSkip 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:

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

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

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

backup, restore and restore-points

Terminal window
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.

Terminal window
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 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.

FlagEffect
--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.
--forceOverwrite a destination that already holds a namespace.
--verifyRe-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:

Terminal window
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
────────────────────────────────────────────────
FlagDefaultEffect
--store <URI>in-memoryWhere to write the graph. Without it the load only reports counts.
-n, --namespacedefaultNamespace name when --store is omitted.
--labelNoteLabel for note nodes.
--edge-typeLINKS_TOEdge type for wikilinks.
--pruneoffMirror the vault: tombstone notes and links that disappeared since the last load.
--placeholdersoffCreate stub :Note nodes (placeholder: true) for links whose target does not exist.
--embedoffStore an embedding per note for vector search, using a local, deterministic, offline embedder.
--watchoffKeep watching the folder and re-sync on every change until interrupted. Implies --prune.

What becomes what:

MarkdownGraph
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.

Terminal window
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:

Terminal window
cargo install --locked --path crates/namidb-cli --features namidb-markdown/remote-embedder

and configure it with environment variables:

VariableMeaning
NAMIDB_EMBEDDER=remoteRequired to switch from the local embedder to a remote provider.
NAMIDB_EMBED_PROVIDERopenai (default), voyage, cohere, gemini or jina.
NAMIDB_EMBED_MODELModel name. Defaults: text-embedding-3-large, voyage-4-large, embed-v4.0, gemini-embedding-001, jina-embeddings-v4.
NAMIDB_EMBED_DIMOutput dimension, default 1024.
NAMIDB_EMBED_API_KEYAPI 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_URLOverride the provider endpoint (for a proxy or compatible gateway).

To serve a vault to an AI agent, see the MCP server.

version

Terminal window
namidb version
# namidb 3.3.0