CLI Reference

hmdb is the HyperMesh DB command-line interface.

Global options

hmdb [--db DIR] <subcommand> [options]

Flag	Default	Description
--db	$HMDB_DIR or ./hypermeshdb	Database directory

Server

hmdb serve

Start the REST API server.

hmdb serve [options]

Flag	Default	Description
--host	0.0.0.0	Bind address
--port	8000	TCP port
--workers	1	Uvicorn worker count
--log-level	info	Logging level
--audit-log	—	JSON audit log file path
--tls-cert	—	TLS certificate path
--tls-key	—	TLS private key path
--no-auth	—	Disable authentication (dev only)

Examples:

# Development (no auth)
hmdb serve --db /tmp/mydb --no-auth

# Production with TLS
hmdb serve --db /data --tls-cert /certs/server.crt --tls-key /certs/server.key \
           --log-level info --audit-log /var/log/hmdb-audit.jsonl

Key management

hmdb add-key

Create a new API key.

hmdb add-key --role readwrite --description "ci-pipeline"

Flag	Default	Description
--role	readonly	readonly / readwrite / admin
--description	""	Human-readable label

---

hmdb list-keys

List all API keys.

hmdb list-keys

---

hmdb revoke-key

Revoke an API key by its ID.

hmdb revoke-key key_a3f9c2b1

Compaction

hmdb compact

Compact the WAL.

hmdb compact [--ttl SECONDS] [--table TABLE]

Flag	Description
--ttl	Discard records older than this many seconds
--table	Compact only the named table

---

hmdb autocompact

Configure auto-compact threshold.

hmdb autocompact --threshold 1000 [--table TABLE]

Backup & Restore

hmdb backup

Create a backup archive.

hmdb backup --out /backups [--no-compact]

Flag	Default	Description
--out	./backups	Output directory
--no-compact	—	Skip pre-backup compaction

---

hmdb restore

Restore from a backup archive.

hmdb restore /backups/hypermeshdb_20260409_120000.tar.gz --target /data/restored

Migration

hmdb migrate

Migrate an older flat-file database to the per-table directory layout.

hmdb migrate --from /old_db --to /new_db

Analytics

hmdb analytics

Compute a hypergraph analytics measure and print the result.

hmdb analytics --table CoProximity --measure pagerank
hmdb analytics --table CoProximity --measure spectral_gap

Shell

hmdb shell

Open an interactive Cypher REPL.

hmdb shell --db /tmp/mydb

hypermeshdb> CREATE HYPEREDGE TABLE Events (Node)
hypermeshdb> INSERT INTO Events (event_ts, members) VALUES (1000, [1,2,3])
hypermeshdb> MATCH HYPEREDGE (he:Events) WHERE he.event_ts >= 1000 RETURN *