NornicDB

CLI Commands ​

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:

bash
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.
  • nornicdb stemmer check <manifest> — check that a BM25 stemmer plugin loads into this binary, as it would at startup (no data directory or network). On success it also prints a nornicdb-stemmer-check: {...} result line (plugin id, version, API version, library SHA-256) for programs that run it.

For migration, backup, and import operations, use the HTTP/Bolt APIs, the runnable scripts under scripts/migration/, or the offline admin guide at admin-tool.md. The main nornicdb server CLI does not have general-purpose import or export subcommands; those live under nornicdb-admin.

BM25 Snowball stemmer packaging is intentionally separate from both nornicdb and nornicdb-admin. Use the standalone nornicdb-snowball helper to wrap generated Snowball Go source as a local stemmer plugin; see BM25 Stemmer Plugins. nornicdb-snowball package --target <nornicdb binary> runs nornicdb stemmer check on the result and keeps the plugin only if that binary loads it.

nornicdb serve ​

Start the NornicDB server with Bolt protocol and HTTP API.

bash
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: explicitly disable authentication. Container startup emits a high-severity structured event when NORNICDB_NO_AUTH=true selects this mode; security validation does not reject the explicit override in any environment.
  • --headless: disable embedded UI assets, SPA/bootstrap routes, and browser IDEs. Core APIs remain available.

Example:

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

nornicdb init ​

Initialize a new NornicDB data directory.

bash
nornicdb init --data-dir ./mydb

Creates the directory layout the server expects on first boot.

nornicdb shell ​

Interactive Cypher query shell.

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

text
$ 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.

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

Flags:

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

Example:

text
$ 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:

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.

bash
nornicdb decay stats --data-dir ./data

Flags:

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

Example output:

text
$ 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.

bash
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.
bash
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:

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

Permission errors:

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