Reference

The EventDBX CLI, demystified.

Operate clusters, deploy schemas, rotate tokens, and inspect data from one binary. Use these commands interactively or inside CI scripts—the CLI registers as both eventdbx and the shorter dbx.

Start the guide View source

$ dbx --help
Usage: dbx [OPTIONS] <COMMAND>

Global options:
    --config <PATH>
    --data-dir <PATH>
    --socket <ADDR>
    -v, --verbose

Global flags

Configure logging, target nodes, and output defaults at the top level. Every subcommand inherits these values.

$ eventdbx --config ./config.toml --data-dir ./state start --foreground
$ eventdbx --socket 127.0.0.1:7000 status
$ EVENTDBX_TOKEN=$(eventdbx token generate ...) eventdbx aggregate list

Tips

eventdbx completions writes shell completions.
EVENTDBX_TOKEN environment variable saves you from repeating --token.
--output json formats responses for automation.

Cluster lifecycle

Start, stop, and inspect servers

$ eventdbx start --foreground --api all
$ eventdbx stop
$ eventdbx status

When the server runs in the background, the CLI maintains a socket for remote control. Commands proxy through that socket whenever direct storage access is locked.

Useful flags

--api filters surfaces (rest, graphql, grpc).
--data-dir points at the RocksDB location.
--restrict=false relaxes schema enforcement for prototypes.

Schema management

Codify aggregates

$ eventdbx schema create \
    --aggregate patient \
    --events patient-added,patient-updated \
    --snapshot-threshold 100

$ eventdbx schema list
$ eventdbx schema validate ./schemas/patient.json

Schemas define which events are accepted and how frequently snapshots are taken. Export them for audits or mirror them across environments.

Commands

schema create builds definitions from flags.
schema import registers JSON files.
schema export prints registered definitions.
schema delete retires unused aggregates.

Access control

Manage tokens and groups

$ eventdbx token generate \
    --group admin \
    --user platform \
    --expiration 3600

$ eventdbx token list
$ eventdbx token revoke --token-id TOKEN_ID

Tokens are JWTs signed by the server. Scope permissions by group and automate rotation in your deployment pipelines.

Best practices

Short expirations for CI and staging environments.
Dedicated groups per workload (etl, support, admin).
Automate rotation with scheduled jobs or deployment hooks.

Data operations

Read and write aggregates

$ eventdbx aggregate apply patient p-002 patient-added \
    --field name="Jane Doe" \
    --field status=active

$ eventdbx aggregate events patient p-002 --take 10
$ eventdbx aggregate get patient p-002

The CLI mirrors every REST endpoint. When the server is offline, commands fall back to the local RocksDB store for offline workflows.

Handy extras

aggregate verify compares Merkle roots across replicas.
aggregate export streams events to NDJSON for analytics.
aggregate import replays events into new environments.