CLI Reference — `hmdb`

The hmdb command-line tool is installed automatically by pip install -e ..

hmdb [--version] COMMAND [options] DB_DIR [...]

---

Global options

Option	Description
--version	Print version and exit
--help	Show help and exit

---

hmdb import

Build the TPI+FMI index from CSV source files. Must be run before any other command.

hmdb import DB_DIR --edges FILE [--nodes FILE] [--bucket-seconds N]

Options

Option	Default	Description
--edges FILE	required	Path to hyperedges CSV
--nodes FILE	—	Path to node-properties CSV (optional)
--bucket-seconds N	10	TPI time-bucket width in seconds

Hyperedges CSV columns: event_ts, members, member_count, weight, mean_dist_m, formation

Example

hmdb import ./my_db \
  --edges  server/swarm_data/hyperedges.csv \
  --nodes  server/swarm_data/nodes_drone.csv \
  --bucket-seconds 10

---

hmdb info

Print database statistics and list hyperedge tables.

hmdb info DB_DIR

Example output

  Database directory : /path/to/my_db
  Total records      : 1,774
  Bucket count       : 86
  Bucket seconds     : 10
  Unique nodes       : 20
  WAL pending        : 0

---

hmdb shell

Start an interactive Cypher query shell with readline history.

hmdb shell DB_DIR

Special commands inside the shell

Command	Description
HELP or ?	Show help
QUIT or EXIT	Exit
.tables	Shortcut for CALL show_hyperedge_tables()
.info	Show database statistics
.compact	Compact WAL into TPI+FMI

Command history is saved to ~/.hmdb_history across sessions.

---

hmdb query

Execute a single Cypher query and print results to stdout.

hmdb query DB_DIR CYPHER [--format {table|csv}]

Options

Option	Default	Description
--format	table	Output format: table (Unicode box-drawing) or csv

Examples

# Unicode table output
hmdb query ./my_db \
  "MATCH HYPEREDGE (he:CoProximity) WHERE he.event_ts >= 0 AND he.event_ts <= 100 RETURN *"

# CSV output (pipe-friendly)
hmdb query ./my_db \
  "CALL show_hyperedge_tables() RETURN *" \
  --format csv

---

hmdb export

Execute a query and write the full result set to a CSV file.

hmdb export DB_DIR --query CYPHER --output FILE

Options

Option	Description
--query CYPHER	Query to execute (required)
--output FILE	Destination CSV file path (required)

Example

hmdb export ./my_db \
  --query  "MATCH HYPEREDGE (he:CoProximity) RETURN *" \
  --output full_dump.csv

---

hmdb insert

Insert a single hyperedge record into the WAL.

hmdb insert DB_DIR --ts N --members N1,N2,... [options]

Options

Option	Default	Description
--ts N	required	Event timestamp in seconds
--members N1,N2,...	required	Comma-separated member node IDs
--weight F	0.0	Coalition weight (0–1)
--mean-dist F	0.0	Mean pairwise distance in metres
--formation NAME	''	Formation name string

Example

hmdb insert ./my_db --ts 9999 --members 1,2,3 --weight 0.95 --formation WEDGE

---

hmdb compact

Compact all WAL entries into the TPI+FMI binary index and truncate the WAL.

hmdb compact DB_DIR

After compact, wal_pending returns 0. Run periodically when wal_pending grows large (rule of thumb: > 10 % of total_records).

Example

hmdb compact ./my_db
# Compacting 47 WAL entries … done  (8.3ms)
# WAL pending after compact: 0