CLI Commands

Complete reference for the aeordb command-line interface.

`aeordb start`

Start the AeorDB server.

aeordb start [OPTIONS]

Flags

Flag	Short	Default	Description
`--config`	`-c`	–	Path to a TOML configuration file
`--port`	`-p`	`6830`	TCP port to listen on
`--host`		`0.0.0.0`	Bind address
`--database`	`-D`	`data.aeordb`	Path to the `.aeordb` database file
`--log-format`		`pretty`	Log output format: `pretty` or `json`
`--auth`		(none)	Auth provider URI (see below)
`--hot-dir`		(database parent dir)	Directory for write-ahead hot files
`--cors-origins`		(disabled)	CORS allowed origins
`--tls-cert`		–	Path to TLS certificate PEM file (requires `--tls-key`)
`--tls-key`		–	Path to TLS private key PEM file (requires `--tls-cert`)
`--jwt-expiry`		`3600`	JWT token lifetime in seconds
`--chunk-size`		`262144`	Write chunk size in bytes (256 KiB)
`--peers`		–	Comma-separated peer URLs to register at startup (persisted, idempotent)
`--join`		–	URL of an existing cluster member to join (one-shot; fetches the cluster’s signing key)
`--join-token`		–	Root API key (or bearer token) of the existing cluster member, required with `--join`

Auth Modes

The --auth flag accepts several formats:

Value	Mode	Description
(not set)	Disabled	No authentication required (dev mode)
`false`, `null`, `no`, `0`	Disabled	Explicitly disable authentication
`self`	Self-contained	AeorDB manages API keys internally
`file:///path/to/identity`	File-based	Load identity from a file

When using self mode, the root API key is printed once on first startup. Save it – it cannot be retrieved again (but can be reset with emergency-reset).

CORS

Value	Behavior
(not set)	CORS disabled
`*`	Allow all origins
`https://a.com,https://b.com`	Allow specific comma-separated origins

Examples

# Development mode (no auth, default port)
aeordb start

# Production with auth on port 8080
aeordb start --port 8080 --database /var/lib/aeordb/prod.aeordb --auth self --log-format json

# Custom hot directory and CORS
aeordb start --database data.aeordb --hot-dir /fast-ssd/hot --cors-origins "*"

# HTTPS with TLS
aeordb start --tls-cert /etc/ssl/cert.pem --tls-key /etc/ssl/key.pem --port 443

# Using a config file
aeordb start --config aeordb.toml

# Config file with CLI overrides
aeordb start --config aeordb.toml --port 8080 --auth false

# Join an existing cluster (one-shot — adopts the cluster's JWT signing key)
aeordb start --database nodeB.aeordb --auth self \
  --join http://nodeA:6830 --join-token "$NODE_A_ROOT_KEY"

# Register additional peers on a node already in a cluster
aeordb start --database data.aeordb --peers "http://nodeC:6830,http://nodeD:6830"

# Show version
aeordb --version

What Happens on Start

Binds HTTP and serves /system/health with status: "starting"
Scans the configured emergency-spill locations for unresolved artifacts tied to this database and refuses startup if any are found
Opens (or creates) the database file
Rebuilds startup state from the WAL if the previous shutdown was dirty
Bootstraps root API key (if --auth self and no key exists yet)
Resets any tasks left in Running state from a previous crash to Pending
Starts background workers:
- Heartbeat: emits clock-sync pulses every 15 seconds
- Metrics: emits system metrics snapshots every 15 seconds
- Cron scheduler: checks /.config/cron.json every 60 seconds
- Task worker: dequeues and executes background tasks
- Webhook dispatcher: delivers events to registered webhook URLs
Switches the full API router to ready and emits server_ready on eligible SSE streams
On CTRL+C or SIGTERM, stops accepting new storage work, waits for active work to drain, then flushes buffers

The shutdown drain window defaults to 600 seconds. Set AEORDB_SHUTDOWN_OPERATION_WAIT_SECS to override it.

`aeordb verify`

Verify database integrity and optionally repair recoverable issues.

aeordb verify [OPTIONS]

Flags

Flag	Short	Default	Description
`--database`	`-D`	`data.aeordb`	Path to the `.aeordb` database file
`--repair`		`false`	Repair recoverable issues
`--force-fix-in-place`		`false`	Apply repairs directly to the original database instead of creating `<database>.repaired`
`--yes`		`false`	Accept emergency-spill replay prompts without interactive confirmation

Examples

# Verify without modifying the database
aeordb verify --database data.aeordb

# Repair into a copy
aeordb verify --repair --database data.aeordb

# Repair the original database in place
aeordb verify --repair --force-fix-in-place --database data.aeordb

# Unattended emergency-spill repair after reviewing the artifacts
aeordb verify --repair --force-fix-in-place --yes --database data.aeordb

aeordb verify reports damaged B-tree directory branches under the Directory Consistency section. Normal read paths can return the readable portion of a damaged B-tree directory, but verification surfaces the missing or corrupt branch so it is not silently hidden.

When --repair is used, B-tree directory issues are repaired by first rebuilding only the affected B-tree directory from current live path records. If targeted repair cannot recover the issue, repair falls back to rebuilding the live directory tree from path-key FileRecords.

Emergency Spill Recovery

If startup finds unresolved emergency-spill artifacts for the target database, it exits before serving the normal API and prints the repair command:

aeordb verify --repair --force-fix-in-place -D /path/to/database.aeordb

Repair scans all emergency-spill locations, orders matching artifacts oldest-first, prints the hot-tail and WAL-tail files it found, and prompts before replay. --yes skips the prompt for automation. Spill replay must run in place because the artifact marker belongs to the original database path.

WAL-tail bytes are the only spill payload replayed into the database file. hot-tail.bin and index-buffer.json are preserved and reported, but repair does not trust them as primary data: after WAL-tail replay it forces a WAL rebuild, reconstructs reusable gaps, and publishes a fresh hot tail.

`aeordb gc`

Run garbage collection to reclaim space from unreachable entries.

aeordb gc [OPTIONS]

Flags

Flag	Short	Default	Description
`--database`	`-D`	`data.aeordb`	Path to the `.aeordb` database file
`--dry-run`		`false`	Report what would be collected without actually deleting

Examples

# Run GC
aeordb gc --database data.aeordb

# Preview what would be collected
aeordb gc --database data.aeordb --dry-run

Output

AeorDB Garbage Collection
Database: data.aeordb

Versions scanned: 3
Live entries:     1247
Garbage entries:  89
Reclaimed:        1.2 MB
Duration:         0.3s

See Garbage Collection for details on the mark-and-sweep algorithm.

`aeordb export`

Export a version as a self-contained .aeordb file.

aeordb export [OPTIONS]

Flags

Flag	Short	Default	Description
`--database`	`-D`	`data.aeordb`	Source database file
`--output`	`-o`	(required)	Output `.aeordb` file path
`--snapshot`	`-s`	(none)	Named snapshot to export
`--hash`		(none)	Specific version hash to export (hex-encoded)

If neither --snapshot nor --hash is provided, HEAD is exported.

Examples

# Export HEAD
aeordb export --database data.aeordb --output backup.aeordb

# Export a named snapshot
aeordb export --database data.aeordb --output backup-v1.aeordb --snapshot v1

# Export a specific hash
aeordb export --database data.aeordb --output backup.aeordb --hash abc123def456...

The output file must not already exist.

See Backup & Restore for full backup workflows.

`aeordb diff`

Create a patch .aeordb containing only the changeset between two versions.

aeordb diff [OPTIONS]

Flags

Flag	Short	Default	Description
`--database`	`-D`	`data.aeordb`	Source database file
`--output`	`-o`	(required)	Output patch file path
`--from`		(required)	Base version (snapshot name or hex hash)
`--to`		HEAD	Target version (snapshot name or hex hash)

Examples

# Diff between two snapshots
aeordb diff --database data.aeordb --output patch.aeordb --from v1 --to v2

# Diff from a snapshot to HEAD
aeordb diff --database data.aeordb --output patch.aeordb --from v1

# Diff between raw hashes
aeordb diff --database data.aeordb --output patch.aeordb --from abc123... --to def456...

The --from and --to arguments first try snapshot name lookup, then fall back to interpreting the value as a hex-encoded hash.

See Backup & Restore for incremental backup workflows.

`aeordb import`

Import an export or patch .aeordb file into a target database.

aeordb import [OPTIONS]

Flags

Flag	Short	Default	Description
`--database`	`-D`	`data.aeordb`	Target database file
`--file`	`-f`	(required)	Backup or patch file to import
`--force`		`false`	Skip base version verification for patches
`--promote`		`false`	Automatically set HEAD to the imported version

Examples

# Import a full backup
aeordb import --database data.aeordb --file backup.aeordb

# Import and promote HEAD
aeordb import --database data.aeordb --file backup.aeordb --promote

# Force-import a patch even if base doesn't match
aeordb import --database data.aeordb --file patch.aeordb --force --promote

Patch Base Verification

When importing a patch (backup_type=2), AeorDB verifies that the target database’s HEAD matches the patch’s base version. Use --force to bypass this check.

See Backup & Restore for restore workflows.

`aeordb promote`

Promote a version hash to HEAD.

aeordb promote [OPTIONS]

Flags

Flag	Short	Default	Description
`--database`	`-D`	`data.aeordb`	Database file
`--hash`		(required)	Hex-encoded version hash to promote

Examples

aeordb promote --database data.aeordb --hash abc123def456...

The command verifies the hash exists in the database before promoting.

`aeordb stress`

Run stress tests against a running AeorDB instance.

aeordb stress [OPTIONS]

Flags

Flag	Short	Default	Description
`--target`	`-t`	`http://localhost:6830`	Target server URL
`--api-key`	`-a`	(required)	API key for authentication
`--concurrency`	`-c`	`10`	Number of concurrent workers
`--duration`	`-d`	`10s`	Test duration (e.g., `30s`, `5m`)
`--operation`	`-o`	`mixed`	Operation type: `write`, `read`, or `mixed`
`--file-size`	`-s`	`1kb`	File size for writes (e.g., `512b`, `1kb`, `1mb`)
`--path-prefix`	`-p`	`/stress-test`	Path prefix for stress test files

Examples

# Quick mixed read/write test
aeordb stress --api-key $API_KEY

# Heavy write test for 5 minutes
aeordb stress --api-key $API_KEY --operation write --concurrency 50 --duration 5m --file-size 10kb

# Read-only test against production
aeordb stress --target https://prod.example.com --api-key $API_KEY --operation read --concurrency 100 --duration 30s

`aeordb emergency-reset`

Revoke the current root API key and generate a new one. Use this if the root key is lost or compromised.

aeordb emergency-reset [OPTIONS]

Flags

Flag	Short	Default	Description
`--database`	`-D`	(required)	Database file
`--force`		`false`	Skip confirmation prompt

Examples

# Interactive (prompts for confirmation)
aeordb emergency-reset --database data.aeordb

# Non-interactive
aeordb emergency-reset --database data.aeordb --force

What Happens

Finds all API keys linked to the root user (nil UUID)
Revokes each one
Generates a new root API key
Prints the new key (shown once, save it immediately)

WARNING: This will invalidate the current root API key.
A new root API key will be generated.
Proceed? [y/N]: y
Revoked 1 existing root API key(s).

==========================================================
  NEW ROOT API KEY (shown once, save it now!):
  aeordb_abc123def456...
==========================================================

This command requires direct file access to the database – it cannot be run over HTTP. It is intended for recovery scenarios where you have lost the root API key.

AeorDB Documentation

CLI Commands

`aeordb start`

Flags

Auth Modes

CORS

Examples

What Happens on Start

`aeordb verify`

Flags

Examples

Directory Tree Repair

Emergency Spill Recovery

`aeordb gc`

Flags

Examples

Output

`aeordb export`

Flags

Examples

`aeordb diff`

Flags

Examples

`aeordb import`

Flags

Examples

Patch Base Verification

`aeordb promote`

Flags

Examples

`aeordb stress`

Flags

Examples

`aeordb emergency-reset`

Flags

Examples

What Happens

See Also

Keyboard shortcuts

AeorDB Documentation