CLI Commands

May 18, 2026 · View on GitHub

Command-line interface for managing NornicDB databases.

Overview

NornicDB ships a single CLI binary (nornicdb) for starting the server and running a small set of database-management subcommands. Most subcommands accept the --data-dir flag to point at the database location; default is ./data.

Installation

The CLI is built from source:

go build -o nornicdb ./cmd/nornicdb
# or install globally
go install ./cmd/nornicdb

Available Commands

The CLI surface is intentionally small. The full set is:

  • nornicdb version — print build version.
  • nornicdb serve — start the server.
  • nornicdb init — initialize a new data directory.
  • nornicdb shell — interactive Cypher query shell.
  • nornicdb decay suppress — re-evaluate suppression status.
  • nornicdb decay stats — print decay statistics.

For migration, backup, and import operations, use the HTTP/Bolt APIs or the runnable scripts under scripts/migration/. The CLI does not have import, export, backup, or restore subcommands.

nornicdb serve

Start the NornicDB server with Bolt protocol and HTTP API.

nornicdb serve \
  --data-dir ./data \
  --bolt-port 7687 \
  --http-port 7474

Common flags:

  • --data-dir: database directory (default: ./data; env: NORNICDB_DATA_DIR).
  • --bolt-port: Bolt protocol port (default: 7687; env: NORNICDB_BOLT_PORT).
  • --http-port: HTTP API port (default: 7474; env: NORNICDB_HTTP_PORT).
  • --address: bind address (default: 0.0.0.0).
  • --no-auth: disable authentication (development only).
  • --headless: disable web UI.

Example:

nornicdb serve --data-dir /var/lib/nornicdb --bolt-port 7687

nornicdb init

Initialize a new NornicDB data directory.

nornicdb init --data-dir ./mydb

Creates the directory layout the server expects on first boot.

nornicdb shell

Interactive Cypher query shell.

nornicdb shell --data-dir ./data

Features:

  • Interactive prompt: nornicdb>.
  • Execute Cypher queries directly.
  • Tabular result display.
  • Exit with exit, quit, or Ctrl+D.

Example session:

$ nornicdb shell --data-dir ./data
📂 Opening database at ./data...
✅ Connected to NornicDB
Type 'exit' or Ctrl+D to quit
Enter Cypher queries (end with semicolon or newline):

nornicdb> MATCH (n) RETURN count(n) AS total
total
---
42

(1 row(s))

nornicdb> exit
👋 Goodbye!

Flags:

  • --data-dir: database directory (required).

nornicdb decay suppress

Suppress nodes whose decay scores fall below the visibility threshold. Sets suppressed: true and suppressed_at on each affected node; suppressed nodes are hidden from normal queries but remain in storage and can be revealed with the reveal() Cypher function.

nornicdb decay suppress --data-dir ./data --threshold 0.10

Flags:

  • --data-dir: database directory (default: ./data).
  • --threshold: visibility threshold (default: 0.05).

Example:

$ nornicdb decay suppress --data-dir ./data --threshold 0.10
📂 Opening database at ./data...
📊 Loading nodes...
📦 Suppressing nodes with decay score < 0.10...
✅ Suppressed 127 nodes

To inspect suppressed nodes from Cypher:

MATCH (n) WHERE reveal(n) AND n.suppressed = true
RETURN n.id, n.suppressed_at, decayScore(n)
ORDER BY decayScore(n);

nornicdb decay stats

Display decay statistics.

nornicdb decay stats --data-dir ./data

Flags:

  • --data-dir: database directory (default: ./data).

Example output:

$ nornicdb decay stats --data-dir ./data
📂 Opening database at ./data...
📊 Decay Statistics:
  Total nodes: 10,000
  High (>0.5): 6,500
  Medium (0.1-0.5): 2,800
  Low (<0.1): 573
  Suppressed: 127
  No profile: 1,200 (score: 1.0)

nornicdb version

Print version information.

nornicdb version

Knowledge-Layer Scoring

Decay behavior, visibility thresholds, and promotion tiers are authored through Cypher DDL (CREATE DECAY PROFILE, CREATE PROMOTION POLICY). The CLI subcommands above are operational helpers; the configuration surface is Cypher. See:

Environment Variables

The most common server flags also have environment-variable counterparts:

  • NORNICDB_DATA_DIR — default data directory.
  • NORNICDB_BOLT_PORT — default Bolt port.
  • NORNICDB_HTTP_PORT — default HTTP port.
export NORNICDB_DATA_DIR=/var/lib/nornicdb
nornicdb shell  # uses /var/lib/nornicdb automatically

For the full configuration surface, see Environment Variables Reference and Configuration.

Troubleshooting

Database not found:

ls -la /path/to/data
nornicdb init --data-dir /path/to/data   # initialize if needed

Permission errors:

chmod 755 /path/to/data
chown -R $USER:$USER /path/to/data