> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eventdbx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Complete guide to the dbx command surface—lifecycle, schemas, aggregates, events, plugins, and upgrades.

The `dbx` CLI is the single entry point for starting the daemon, managing schemas, writing events, and supervising plugins. Every command accepts `--config <path>` if you need to target a non-default configuration file.

## Server lifecycle

* `dbx start [--port <u16>] [--data-dir <path>] [--foreground] [--restrict=<off|default|strict>]` – launch the daemon. `default` validates when schemas exist; `strict` requires schemas for every aggregate; `off` bypasses validation entirely.
* `dbx stop` – stop the running daemon referenced by the PID file.
* `dbx status` – print port, PID, uptime, and restriction mode.
* `dbx restart [start options…]` – stop then start with new options.
* `dbx destroy [--yes]` – remove the PID file, data dir, and config after confirmation.

## Configuration

`dbx config [--port <u16>] [--data-dir <path>] [--cache-threshold <usize>] [--dek <base64>] [--list-page-size <usize>] [--page-limit <usize>] [--plugin-max-attempts <u32>] [--snapshot-threshold <u64>] [--clear-snapshot-threshold]`

* First invocation should set a 32-byte base64 DEK so payloads, snapshots, and `tokens.json` are encrypted.
* `--list-page-size` changes the default page size for `aggregate list`; `--page-limit` caps any requested page.
* `--plugin-max-attempts` controls how many retries occur before a job becomes “dead”.

## Domains

* `dbx checkout <domain> [--create|--delete] [--force] [--remote <host[:port]>] [--port <u16>] [--token <value>] [--remote-tenant <id>]` – activate a domain (creating or deleting it with the flags) and optionally store remote replication settings in `remote.json` for later `push`/`pull`/`watch` commands.
* `dbx merge --from <domain> [--into <domain>] [--overwrite-schemas]` – copy events + schemas from one domain into another. Existing aggregates abort unless explicitly overwritten.

## Tokens

* `dbx token generate --group <name> --user <name> [--expiration <secs>] [--limit <writes>] [--keep-alive]`
* `dbx token list`
* `dbx token revoke --token <value>`
* `dbx token refresh --token <value> [--expiration <secs>] [--limit <writes>]`

Tokens are Ed25519 signed; keys live under `[auth]` in `config.toml`.
See [Authorization](/core-concepts/authorization) for action/resource patterns, tenant scoping, and example token recipes.

## Tenants

* `dbx tenant assign <tenant> --shard <shard-0001>` – pin a tenant to a shard label instead of hashing across the configured shard count.
* `dbx tenant unassign <tenant>` – drop the manual shard override.
* `dbx tenant list [--shard <shard-0001>] [--json]` – print assignments plus `quota_mb` and `usage_mb` columns so you can watch noisy tenants in plain text or JSON.
* `dbx tenant stats [--json]` – summarise how many explicit assignments sit on each shard.
* `dbx tenant quota set <tenant> --max-mb <n>` / `dbx tenant quota clear <tenant>` – enforce or remove per-tenant storage ceilings.
* `dbx tenant quota recalc <tenant>` – rescan a tenant’s RocksDB files to refresh usage counters after restores or manual maintenance.

## Schemas

* `dbx schema create <name> --events <event1,event2,...> [--snapshot-threshold <u64>]`
* `dbx schema add <name> --events <event1,event2,...>`
* `dbx schema remove <name> <event>`
* `dbx schema annotate <name> <event> [--note <text>] [--clear]`
* `dbx schema list`

Schemas are stored on disk and enforced whenever restriction mode is `default` or `strict`.

## Aggregates

* `dbx aggregate create --aggregate <type> --aggregate-id <id> --event <name> [--field KEY=VALUE...] [--payload <json>] [--metadata <json>] [--note <text>] [--token <value>] [--json]`
* `dbx aggregate apply --aggregate <type> --aggregate-id <id> --event <name> --field KEY=VALUE... [--payload <json>] [--publish PLUGIN[:MODE[:PRIORITY]] ...] [--stage] [--token <value>] [--note <text>]`
* `dbx aggregate patch --aggregate <type> --aggregate-id <id> --event <name> --patch <json> [--publish PLUGIN[:MODE[:PRIORITY]] ...] [--stage] [--token <value>] [--metadata <json>] [--note <text>]`
* `dbx aggregate list [--aggregate <type>] [--cursor <token>] [--take <n>] [--stage] [--filter <expr>] [--sort <field[:order],...>] [--include-archived|--archived-only]`
* `dbx aggregate get --aggregate <type> --aggregate-id <id> [--version <u64>] [--include-events]`
* `dbx aggregate verify --aggregate <type> --aggregate-id <id>`
* `dbx aggregate snapshot --aggregate <type> --aggregate-id <id> [--comment <text>]`
* `dbx aggregate archive|restore --aggregate <type> --aggregate-id <id> [--comment <text>]`
* `dbx aggregate remove --aggregate <type> --aggregate-id <id>` – only succeeds when version is still 0.
* `dbx aggregate commit` – flush all staged events in a single atomic batch.

`--publish` can be repeated to target specific plugins per write (`PLUGIN[:MODE[:PRIORITY]]`); omit it to fan out to all enabled plugins using their configured payload modes.

Complexity hints live on the [features page](/features#aggregate-operation-costs). Hot aggregates typically stay in the RocksDB block cache, keeping latency near-constant.

## Events

* `dbx events [--aggregate <type>] [--aggregate-id <id>] [--cursor <token>] [--take <n>] [--filter <expr>] [--sort <field[:order],...>] [--json] [--include-archived|--archived-only]`
* `dbx events --event <snowflake_id> [--json]` – omit `--event` if the first positional argument is a Snowflake id.
* `dbx aggregate export [<type>] [--all] --output <path> [--format csv|json] [--zip] [--pretty]`

`--filter` accepts SQL-like expressions (for example, `payload.status = "open" AND metadata.note LIKE "retry%"`). Prefix fields with `payload.`, `metadata.`, or `extensions.`.

## Snapshots

* `dbx snapshots list [--aggregate <type>] [--aggregate-id <id>] [--version <n>] [--json]` – enumerate snapshots with optional aggregate scoping and version filters.
* `dbx snapshots create <aggregate> <aggregate_id> [--comment <text>]` – materialise a new snapshot of the current aggregate state.
* `dbx snapshots get <snapshot_id> [--json]` – fetch a specific snapshot by Snowflake id.

## Plugins and queues

* `dbx plugin install|enable|disable|remove`
* `dbx plugin start|stop|status <name>` – manage supervised process plugin workers.
* `dbx plugin config tcp|http|log|process` – choose payload slices via `--payload <all|event-only|state-only|schema-only|event-and-schema|extensions-only>`.
* `dbx plugin test [<name>…]`
* `dbx plugin list`
* `dbx plugin replay <plugin> <aggregate> [<aggregate_id>] [--payload-mode <all|event-only|state-only|schema-only|event-and-schema|extensions-only>]`
* `dbx queue`, `dbx queue clear`, `dbx queue retry [--event-id <job-id>]`

Queues guarantee delivery with exponential backoff. Clearing dead entries prompts for confirmation to avoid accidental loss.

## Replication & automation

* `dbx push <remote> [--aggregate <type>] [--id <id>]`
* `dbx pull <remote> [--aggregate <type>] [--id <id>]`
* `dbx watch <remote> --mode <push|pull|bidirectional> [--aggregate <type>] [--interval <secs>] [--background] [--run-once] [--skip-if-active]`
* `dbx watch status <remote> [--all]`

Replications abort if either side diverges for a given aggregate. Use `--concurrency <threads>` on push/pull to tune throughput when mirroring large domains.

## Upgrades

* `dbx upgrade [<version>|latest] [--no-switch] [--print-only]` – downloads the requested release to `~/.eventdbx/versions/<target>/<tag>/` and switches the active binary unless `--no-switch` is set.
* `dbx upgrade use <version>` – jump between installed releases without downloading.
* `dbx upgrade installed [--json]`
* `dbx upgrade --suppress <version>` / `dbx upgrade --clear-suppress`
* `dbx upgrade list [--limit <n>] [--json]`

Versions lower than `v1.13.2` are unsupported; use `dbx upgrade@<version>` as a shortcut syntax. Set `DBX_NO_UPGRADE_CHECK=1` to silence startup reminders in automation.

## Maintenance

* `dbx backup --output <path> [--force]`
* `dbx restore --input <path> [--data-dir <path>] [--force]`

Always stop the daemon before running backups or restores to keep Merkle trees consistent.