CLI Reference

Install / run

There are two ways to run the CLI. Both accept identical subcommands.

Dev mode (source checkout)

dotnet run --project src/DocumentForge.Cli -- <command> [args]

Published binary

# Build the single-file binary for your platform
./scripts/publish-dfdb.sh     # or publish-dfdb.ps1 on Windows

# Then run it from dist/ — no .NET runtime required on the target
./dist/linux-x64/dfdb <command> [args]
./dist/win-x64/dfdb.exe <command> [args]

In the rest of this page we write dfdb; substitute whichever form fits your setup.

Top-level help

dfdb help        # or --help, -h
dfdb version     # or --version, -v

serve

Start the REST API for a single node. This is what the admin UI, the LINQ client, and the HttpShardTransport talk to.

dfdb serve [--config node.json]
            [--node-name NAME]
            [--port N]
            [--data-dir DIR]
            [--api-key KEY]
            [--replication-secret SECRET]
            [--bind-all]
            [--replication-role leader|follower]
            [--replication-port N]
            [--leader-host H] [--leader-port N]
            [--auto-failover-seconds N] [--auto-failover-new-port N]

Examples

# Single-node dev
dfdb serve --port 5000 --data-dir ./data

# Production node with API key + shared secret
dfdb serve --config ./node-shard-a.json \
           --api-key sk_prod_abc123 \
           --replication-secret repl_shared_xyz

# Everything via env vars (useful in containers)
DFDB_NODE_NAME=shard-a \
DFDB_PORT=5001 \
DFDB_DATA_DIR=/var/lib/dfdb/shard-a \
DFDB_API_KEY=sk_prod_abc123 \
dfdb serve

# Leader with replication enabled
dfdb serve --port 5000 --data-dir ./data/leader \
           --replication-role leader --replication-port 5500

# Follower with auto-failover
dfdb serve --port 5010 --data-dir ./data/replica \
           --replication-role follower \
           --leader-host localhost --leader-port 5500 \
           --auto-failover-seconds 10

inspect

Offline introspection. Opens a .dfdb file locally and prints stats — size, page counts, collections, and indexes. Does not start a server.

dfdb inspect <file>

# Example
dfdb inspect ./data/shard-a/data.dfdb

query

Run a single SQL statement against a local file and print the results. Great for scripts and sanity checks.

dfdb query <file> "<sql>"

# Examples
dfdb query ./data/shard-a/data.dfdb "SELECT COUNT(*) FROM orders"
dfdb query ./data/shard-a/data.dfdb "SELECT * FROM orders WHERE pnr = 'ABC123'"

repl

Interactive SQL console. Opens the file, gives you a prompt, executes statements on Enter. Type stats to see storage info, exit to quit.

dfdb repl <file>

dfdb> SELECT * FROM orders LIMIT 5
dfdb> SELECT status, COUNT(*) FROM orders GROUP BY status
dfdb> CREATE INDEX idx_pnr ON orders (pnr)
dfdb> stats
dfdb> exit

compact

Reclaim physical space left by DELETE. Rewrites the collection's pages in-place, releasing freed slots back to the allocator.

dfdb compact <file> <collection>

# Example
dfdb compact ./data/shard-a/data.dfdb orders

seed

Loads realistic airline-reservation sample data (orders with nested passengers and flights). Useful for demos and smoke tests.

dfdb seed <file> [count]

# Examples
dfdb seed ./data/demo.dfdb               # default 10,000 orders
dfdb seed ./data/demo.dfdb 250000        # a quarter million

cluster

Build and inspect the cluster.json topology file. This file describes every shard and what's sharded vs replicated.

dfdb cluster init            <config>
dfdb cluster show            <config>
dfdb cluster add-shard       <config> <name> <endpoint>
dfdb cluster add-collection  <config> <name> (hash <path>|replicated)

Examples

# Fresh cluster config
dfdb cluster init cluster.json

# Register three shards
dfdb cluster add-shard cluster.json shard-a http://localhost:5001
dfdb cluster add-shard cluster.json shard-b http://localhost:5002
dfdb cluster add-shard cluster.json shard-c http://localhost:5003

# orders are hash-sharded on pnr; airports are fully replicated to every shard
dfdb cluster add-collection cluster.json orders   hash pnr
dfdb cluster add-collection cluster.json airports replicated

# Inspect what we built
dfdb cluster show cluster.json

health

Ping every shard in a cluster config and report status + basic stats. Intended to be safe to run from anywhere — it only reads.

dfdb health <cluster-config>

# Example output: three green dots, response times, doc counts per shard
dfdb health cluster.json

rebalance

Plan or execute a topology change (adding or removing shards). --plan-only prints what would move without touching data.

dfdb rebalance <old-config> <new-config> [--plan-only]

# Preview only — no data moves
dfdb rebalance old-cluster.json new-cluster.json --plan-only

# Execute the migration
dfdb rebalance old-cluster.json new-cluster.json

See the Sharding guide for the online-rebalance protocol and what happens to reads/writes during migration.

node.json format

Full schema. Every field except nodeName, port, and dataDir is optional.

{
  "nodeName": "shard-a",
  "port": 5001,
  "dataDir": "/var/lib/dfdb/shard-a",
  "bindAllInterfaces": false,
  "security": {
    "apiKey": "sk_prod_abc123",
    "replicationSecret": "repl_shared_xyz",
    "tls": {
      "certPath": "/etc/dfdb/cert.pfx",
      "certPassword": "env:DFDB_CERT_PASSWORD"
    }
  },
  "replication": {
    "role": "follower",
    "port": 5500,
    "leaderHost": "leader.internal",
    "leaderPort": 5500,
    "autoFailover": {
      "silenceSeconds": 10,
      "newLeaderPort": 5500
    }
  }
}

Notes:

• bindAllInterfaces: true is equivalent to --bind-all — only enable behind a firewall.
• certPassword supports env:VAR_NAME indirection so you don't commit passwords to the config file.
• Omit the security block entirely for local dev.
• Omit the replication block for a single-node setup. role is either "leader" or "follower".
• On a leader, only role and port are read. On a follower, leaderHost + leaderPort are required; autoFailover is optional.

Environment variables

Every flag on dfdb serve has an env-var equivalent. Useful for containers and orchestrators.

The admin UI also reads one env var at build time:

NEXT_PUBLIC_DFDB_URL=http://localhost:5000 npm run dev

Config precedence

When the same setting is provided by multiple sources, the later one wins:

1. --config node.json — loaded first
2. CLI flags (--port, --data-dir, etc.) — override the config file
3. Env vars (DFDB_*) — fill in anything still at its default
4. Defaults — localhost:5000, ./data, no security

REST API endpoints

Once dfdb serve is running, every database operation is available over HTTP. The Postman collection covers them all with working examples.

Application (CRUD + query)

The natural way to use the API: address documents by their business key (PNR, email, SKU…), not by DocumentForge's internal id.

Application (advanced — by internal _id)

The internal _id is a 16-byte sequential identifier returned by inserts. You normally don't want this — prefer /by/{field}/{value} above. Use these only when you've cached the _id from a prior write and want to skip the index lookup.

Admin

Replication

Postman collection

A ready-to-import Postman collection lives at docs/postman/DocumentForge.postman_collection.json. Two folders:

• Application — how an app uses the database: seed, insert, bulk-insert, find-by-id, SQL queries, create index, delete.
• Database Operations — how a management app / SRE uses it: admin (flush, checkpoint, compact, drop), replication (status, start leader/follower, promote, auto-failover), and a sharding-via-CLI reference.

Setting it up

1. Open Postman → File → Import → choose the DocumentForge.postman_collection.json file.
2. On the collection, set baseUrl (default http://localhost:5000) and, if you started the node with --api-key, set apiKey.
3. Run Application → Seed sample airline data to get ~500 realistic orders + flights with 5 indexes.
4. Pre-request scripts auto-save returned ids to collection variables so Insert → Find → Delete chains work without hand-editing URLs.

See docs/postman/README.md for the variable reference and recommended first-run order.