---
title: CLI Reference
description: Discover every EventDBX CLI command for servers, schemas, tokens, and aggregates.
nav_id: cli
---
<section class="relative overflow-hidden py-24 sm:py-28">
<div class="absolute inset-0 -z-10 bg-[radial-gradient(circle_at_top,_rgba(255,79,109,0.18),_transparent_60%)]"></div>
<div class="mx-auto grid max-w-6xl items-center gap-14 px-6 lg:grid-cols-[minmax(0,1.1fr)_minmax(0,0.9fr)]">
<div class="space-y-7">
<span class="inline-flex items-center gap-2 rounded-full border border-white/10 bg-white/5 px-3 py-1.5 text-xs font-semibold uppercase tracking-[0.3em] text-brand">Reference</span>
<h1 class="text-4xl font-semibold leading-tight text-white sm:text-5xl">The EventDBX CLI, demystified.</h1>
<p class="max-w-xl text-lg text-slate-300">
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 <code class="font-mono text-sm text-slate-200">eventdbx</code> and the shorter <code class="font-mono text-sm text-slate-200">dbx</code>.
</p>
<div class="flex flex-wrap gap-3">
<a class="inline-flex items-center rounded-full bg-brand px-5 py-3 text-sm font-semibold text-slate-950 shadow-glow transition hover:-translate-y-0.5 hover:shadow-xl hover:shadow-brand/40" href="{{ '/getting-started/' | relative_url }}">
Start the guide
</a>
<a class="inline-flex items-center rounded-full border border-brand/40 px-5 py-3 text-sm font-semibold text-brand transition hover:border-brand hover:bg-brand/10" href="https://github.com/thachp/eventdbx">
View source
</a>
</div>
</div>
<div>
<pre class="overflow-x-auto rounded-3xl bg-slate-900/75 p-6 text-sm leading-relaxed text-slate-200 shadow-2xl ring-1 ring-white/10"><code>$ dbx --help
Usage: dbx [OPTIONS] <COMMAND>
Global options:
--config <PATH>
--data-dir <PATH>
--socket <ADDR>
-v, --verbose</code></pre>
</div>
</div>
</section>
<section class="bg-slate-100 py-24 text-slate-900 sm:py-28" id="global">
<div class="mx-auto grid max-w-6xl gap-12 px-6 lg:grid-cols-[minmax(0,1.1fr)_minmax(0,0.9fr)]">
<div class="space-y-4">
<h2 class="text-3xl font-semibold sm:text-4xl">Global flags</h2>
<p class="text-lg text-slate-600">
Configure logging, target nodes, and output defaults at the top level. Every subcommand inherits these values.
</p>
<pre class="overflow-x-auto rounded-3xl bg-white p-6 text-sm leading-relaxed text-slate-800 shadow-xl shadow-slate-400/10 ring-1 ring-slate-200"><code>$ 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</code></pre>
</div>
<div class="rounded-3xl bg-white p-8 shadow-xl shadow-slate-400/10 ring-1 ring-slate-200">
<h3 class="text-lg font-semibold text-slate-900">Tips</h3>
<ul class="mt-5 space-y-3 text-sm text-slate-600">
<li><strong class="text-slate-900">eventdbx completions</strong> writes shell completions.</li>
<li><strong class="text-slate-900">EVENTDBX_TOKEN</strong> environment variable saves you from repeating <code class="font-mono text-xs text-slate-700">--token</code>.</li>
<li><strong class="text-slate-900">--output json</strong> formats responses for automation.</li>
</ul>
</div>
</div>
</section>
<section class="py-24 sm:py-28" id="lifecycle">
<div class="mx-auto grid max-w-6xl gap-12 px-6 lg:grid-cols-[minmax(0,1.1fr)_minmax(0,0.9fr)]">
<div class="space-y-4">
<span class="inline-flex items-center gap-2 rounded-full border border-white/10 bg-white/5 px-3 py-1 text-xs font-semibold uppercase tracking-[0.3em] text-brand">Cluster lifecycle</span>
<h2 class="text-3xl font-semibold text-white sm:text-4xl">Start, stop, and inspect servers</h2>
<pre class="overflow-x-auto rounded-3xl bg-slate-900/70 p-6 text-sm leading-relaxed text-slate-200 shadow-2xl ring-1 ring-white/10"><code>$ eventdbx start --foreground --api all
$ eventdbx stop
$ eventdbx status</code></pre>
<p class="text-lg text-slate-300">
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.
</p>
</div>
<div class="rounded-3xl border border-white/10 bg-slate-900/60 p-8 shadow-2xl shadow-black/30 backdrop-blur">
<h3 class="text-lg font-semibold text-white">Useful flags</h3>
<ul class="mt-5 space-y-3 text-sm text-slate-200">
<li><strong class="text-white">--api</strong> filters surfaces (<code class="font-mono text-xs text-slate-200">rest</code>, <code class="font-mono text-xs text-slate-200">graphql</code>, <code class="font-mono text-xs text-slate-200">grpc</code>).</li>
<li><strong class="text-white">--data-dir</strong> points at the RocksDB location.</li>
<li><strong class="text-white">--restrict=false</strong> relaxes schema enforcement for prototypes.</li>
</ul>
</div>
</div>
</section>
<section class="bg-slate-100 py-24 text-slate-900 sm:py-28" id="schema">
<div class="mx-auto grid max-w-6xl gap-12 px-6 lg:grid-cols-[minmax(0,1.1fr)_minmax(0,0.9fr)]">
<div class="space-y-4">
<span class="inline-flex items-center gap-2 rounded-full border border-brand/10 bg-brand/10 px-3 py-1 text-xs font-semibold uppercase tracking-[0.3em] text-brand">Schema management</span>
<h2 class="text-3xl font-semibold sm:text-4xl">Codify aggregates</h2>
<pre class="overflow-x-auto rounded-3xl bg-white p-6 text-sm leading-relaxed text-slate-800 shadow-xl shadow-slate-400/10 ring-1 ring-slate-200"><code>$ eventdbx schema create \
--aggregate patient \
--events patient-added,patient-updated \
--snapshot-threshold 100
$ eventdbx schema list
$ eventdbx schema validate ./schemas/patient.json</code></pre>
<p class="text-lg text-slate-600">
Schemas define which events are accepted and how frequently snapshots are taken. Export them for audits or mirror them across environments.
</p>
</div>
<div class="rounded-3xl bg-white p-8 shadow-xl shadow-slate-400/10 ring-1 ring-slate-200">
<h3 class="text-lg font-semibold text-slate-900">Commands</h3>
<ul class="mt-5 space-y-3 text-sm text-slate-600">
<li><strong class="text-slate-900">schema create</strong> builds definitions from flags.</li>
<li><strong class="text-slate-900">schema import</strong> registers JSON files.</li>
<li><strong class="text-slate-900">schema export</strong> prints registered definitions.</li>
<li><strong class="text-slate-900">schema delete</strong> retires unused aggregates.</li>
</ul>
</div>
</div>
</section>
<section class="py-24 sm:py-28" id="token">
<div class="mx-auto grid max-w-6xl gap-12 px-6 lg:grid-cols-[minmax(0,1.1fr)_minmax(0,0.9fr)]">
<div class="space-y-4">
<span class="inline-flex items-center gap-2 rounded-full border border-white/10 bg-white/5 px-3 py-1 text-xs font-semibold uppercase tracking-[0.3em] text-brand">Access control</span>
<h2 class="text-3xl font-semibold text-white sm:text-4xl">Manage tokens and groups</h2>
<pre class="overflow-x-auto rounded-3xl bg-slate-900/70 p-6 text-sm leading-relaxed text-slate-200 shadow-2xl ring-1 ring-white/10"><code>$ eventdbx token generate \
--group admin \
--user platform \
--expiration 3600
$ eventdbx token list
$ eventdbx token revoke --token-id TOKEN_ID</code></pre>
<p class="text-lg text-slate-300">
Tokens are JWTs signed by the server. Scope permissions by group and automate rotation in your deployment pipelines.
</p>
</div>
<div class="rounded-3xl border border-white/10 bg-slate-900/60 p-8 shadow-2xl shadow-black/30 backdrop-blur">
<h3 class="text-lg font-semibold text-white">Best practices</h3>
<ul class="mt-5 space-y-3 text-sm text-slate-200">
<li><strong class="text-white">Short expirations</strong> for CI and staging environments.</li>
<li><strong class="text-white">Dedicated groups</strong> per workload (etl, support, admin).</li>
<li><strong class="text-white">Automate rotation</strong> with scheduled jobs or deployment hooks.</li>
</ul>
</div>
</div>
</section>
<section class="bg-slate-100 py-24 text-slate-900 sm:py-28" id="data">
<div class="mx-auto grid max-w-6xl gap-12 px-6 lg:grid-cols-[minmax(0,1.1fr)_minmax(0,0.9fr)]">
<div class="space-y-4">
<span class="inline-flex items-center gap-2 rounded-full border border-brand/10 bg-brand/10 px-3 py-1 text-xs font-semibold uppercase tracking-[0.3em] text-brand">Data operations</span>
<h2 class="text-3xl font-semibold sm:text-4xl">Read and write aggregates</h2>
<pre class="overflow-x-auto rounded-3xl bg-white p-6 text-sm leading-relaxed text-slate-800 shadow-xl shadow-slate-400/10 ring-1 ring-slate-200"><code>$ 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</code></pre>
<p class="text-lg text-slate-600">
The CLI mirrors every REST endpoint. When the server is offline, commands fall back to the local RocksDB store for offline workflows.
</p>
</div>
<div class="rounded-3xl bg-white p-8 shadow-xl shadow-slate-400/10 ring-1 ring-slate-200">
<h3 class="text-lg font-semibold text-slate-900">Handy extras</h3>
<ul class="mt-5 space-y-3 text-sm text-slate-600">
<li><strong class="text-slate-900">aggregate verify</strong> compares Merkle roots across replicas.</li>
<li><strong class="text-slate-900">aggregate export</strong> streams events to NDJSON for analytics.</li>
<li><strong class="text-slate-900">aggregate import</strong> replays events into new environments.</li>
</ul>
</div>
</div>
</section>
<section class="py-24">
<div class="mx-auto max-w-6xl px-6">
<div class="relative overflow-hidden rounded-3xl border border-white/10 bg-gradient-to-br from-brand to-brand-400 p-12 text-slate-950 shadow-2xl shadow-brand/40">
<div class="absolute -right-12 top-12 h-44 w-44 rounded-full bg-white/30 blur-3xl"></div>
<h2 class="text-3xl font-semibold sm:text-4xl">Automate your workflows.</h2>
<p class="mt-4 text-lg text-slate-900/80">
Combine these commands with CI pipelines to ship schema migrations and rollout scripts safely.
</p>
<a class="mt-6 inline-flex items-center rounded-full bg-slate-950 px-6 py-3 text-sm font-semibold text-white transition hover:-translate-y-0.5 hover:bg-slate-900" href="{{ '/getting-started/' | relative_url }}">
Back to the guide
</a>
</div>
</div>
</section>