CLI Overview

The CLI is suitable for both local development and production deployments. It follows a modular structure with dedicated subcommands for each task.

General Structure#

Changed in 1.3The CLI executable is called eventsourcingdb. It provides the subcommands run, diagnostics, and version, besides completion, which generates a script for the autocompletion of your shell, and help. Each subcommand has its own purpose and may support specific flags.

You can get a list of all subcommands and general usage information by running:

./eventsourcingdb --help

To view help for a specific command, append --help to that command, for example:

./eventsourcingdb run --help

Starting the Server#

You can start an EventSourcingDB instance using the run subcommand:

./eventsourcingdb run

By default, this starts the server in HTTPS mode on port 4000 and listens for API requests. You can configure this behavior using CLI flags.

Some flags are mandatory when starting the server, although the help output (eventsourcingdb run --help) does not mark them. If one of them is missing, the CLI exits with an error:

Changed in 1.3--api-token, the API token, which needs at least 32 characters unless the data directory is temporary, and must consist of printable ASCII characters only, without whitespace at its start or end, see API Token.
Exactly one of --data-directory and --data-directory-temporary.
With HTTPS enabled, which is the default, both --https-certificate-file and --https-private-key-file.

Beyond that, at least one of HTTP and HTTPS has to be enabled, the two need different ports if both are, and --license-file and --license-string exclude each other.

Ports and Protocols#

The server supports both HTTP and HTTPS endpoints. In production, you should use HTTPS exclusively. By default, HTTPS is enabled (--https-enabled) and runs on port 4000 (--https-port). You must provide both a certificate (--https-certificate-file) and a private key (--https-private-key-file).

HTTP is disabled by default but can be enabled explicitly using --http-enabled. It runs on port 3000 (--http-port). This may be useful in development or when operating behind a TLS-terminating reverse proxy, where you switch HTTPS off with --https-enabled=false.

Avoid Public Exposure

EventSourcingDB is designed to run inside secure, internal networks. It should not be publicly exposed on the internet. If external access is required, use a reverse proxy with appropriate authentication, TLS termination, and rate-limiting.

API Token#

Changed in 1.3To secure the API, an API token must be provided using the --api-token flag. This token is required for all routes except ping, the OpenAPI definition, and the API catalog, see Authentication. You can choose any string of printable ASCII characters without whitespace at its start or end, but on a data directory, it needs at least 32 characters, and for production deployments, it should be a randomly generated, high-entropy value. The printable ASCII characters are the letters from A to Z in either case, the digits, the space, and the punctuation and symbols of ASCII, such as -, _, or ~.

A shorter token could be guessed by trying, which the rate limit does not prevent: once requests without a valid token have used up the global limit of their own, the answer to a request tells a valid token from an invalid one. What keeps a token from being guessed is its length and randomness, so with a shorter one, a server on a data directory refuses to start, with the error you must specify an API token of at least 32 characters. With --data-directory-temporary, as for trying EventSourcingDB out and in tests, a shorter token such as secret is accepted.

A token with any other character, or with whitespace at its start or end, cannot be relied on to reach the server as it is: some clients refuse to send a control character, such as a tab or the trailing newline of a secret read from a file, others lose the whitespace at its end on the way, and a character beyond ASCII, such as a letter with an umlaut, a no-break space, or the byte order mark that a file saved as UTF-8 with BOM starts with, cannot be presented by the management UI in every browser, since browsers send such a character in different encodings or refuse to send it at all. A bearer token consists of ASCII by RFC 6750 anyway. So the server refuses to start with such a token, also with --data-directory-temporary, with the error you must specify an API token of printable ASCII characters only, without whitespace at its start or end. A space inside the token is accepted.

Changed in 1.3

Access Control

There is currently no role-based access model. Anyone with the token has full access. We recommend a token that consists of uppercase and lowercase letters and digits.

Data Directory#

The database stores its data in a persistent directory defined via --data-directory. This is required for production use.

Added in 1.3EventSourcingDB manages the contents of this directory itself. Do not change, add, or delete anything inside it, not even files that look empty or left over: some of them hold events that have already been confirmed to clients but are not stored anywhere else yet, and one keeps older versions of EventSourcingDB from starting on a directory they cannot read.

EventSourcingDB also keeps other users of the machine out of the files it holds there, see Permissions of the Data Directory.

A data directory belongs to one server at a time: a second server on it refuses to start, see One Server per Data Directory.

The data directory holds the entries of EventSourcingDB itself, on one file system. Where one of them, such as the directory events or wal, is a link or lies on another file system, for example on a disk mounted there, writes into it could not be made durable, so EventSourcingDB refuses to start and names the entry, with the message "events" in the data directory is a link: the server can make writes durable only for what lies in the data directory itself; replace the link by what it points to or "wal" in the data directory lies on another file system: the server can make writes durable only on the file system of the data directory; move it onto that file system. The data directory itself may be a link or a volume of its own.

For testing or demo scenarios, you can use --data-directory-temporary flag to create a temporary store. Unlike an in-memory store, it is written to the system's temporary directory on disk. The data is automatically discarded when the server shuts down. With a temporary store, every license holds for at most 48 hours from the start.

Event SigningAdded in 1.1#

To ensure authenticity and integrity of events, you can configure EventSourcingDB to sign all events returned by the API using the --signing-key-file flag. The signing key must be a PKCS#8-encoded Ed25519 private key in PEM format.

Changed in 1.2When signing is enabled, every event returned from all routes that return events will include a signature field. If no signing key is provided, this field will be null.

Added in 1.1

Signatures Are Calculated On-Demand

Signatures are not stored persistently. They are generated on the fly whenever an event is returned. This means that if you change the signing key, the same event will receive a different signature when fetched again.

For details on how to generate signing keys and verify event signatures in your application, see Verifying Event Signatures.

Read-Only Mode#

For scenarios such as maintenance, audits, or backup validation, you can start the server in read-only mode using the --read-only flag. In this mode, the API accepts only read operations – writes will be rejected.

Requiring Event SchemasAdded in 1.3#

By default, you can write events of any type, whether or not it has a registered schema: a schema is checked only where one exists. To enforce a closed set of known event types, start the server with the --require-event-schemas flag:

./eventsourcingdb run [...] --require-event-schemas

The server then rejects every write whose event type has no registered schema, with the error event-schema-unregistered, so every event type needs a schema before its events can be written. The flag is off by default, because turning it on rejects every type that has no schema yet.

It applies only to new writes: the events already stored are never touched, and enabling the flag does not check them retroactively. An event type that already has events but no schema becomes unwritable until you register a schema for it. To help you find such types, the server logs a warning at startup that lists the existing event types without a schema.

Restoring a backup follows the same rule: with the flag enabled, a backup is restored only if it registers a schema for the type of every event it holds, and is rejected otherwise.

Rate Limiting#

EventSourcingDB limits how many requests each client may send per second, where a write counts as several requests. By default, each client may send 1,000 requests per second for every CPU the database runs on. To change that, use the --rate-limit-requests-per-second flag, which takes 0 or more: a higher value raises the limit, and 0 switches off the limit per client, the limit of open streams per client included, while the global limit remains. With a negative value, the server refuses to start, with the error you must not specify a negative rate limit. For details, see Rate Limiting.

Development Mode#

The development mode (--development-mode) is strictly intended for internal diagnostics and support by the maintainers of EventSourcingDB. It requires a license with elevated permissions and must not be used in regular deployments.

Not for Public Use

Do not use development mode in production or regular testing environments. It is reserved for internal debugging and analysis by the team at the native web GmbH.

Added in 1.3In development mode, and only there, the server serves the profiles of its runtime under /debug/pprof, such as the heap, the goroutines, a CPU profile, and a trace, which the maintainers use to analyze it. Since profiles can reveal data from memory, they require the API token, like the routes of the API, and the command line, which holds the API token and the license, is not served at all. Up to version 1.2, a server served these profiles without a token whenever its license permitted development mode, also when it was not started in it.

Management UI#

The optional web-based management UI can be enabled using --with-ui. This interface provides an overview of the current system state and can be useful for monitoring or debugging.

If you already use other observability tools (e.g. Prometheus, Grafana), the UI may not be necessary.

Changed in 1.3Version 1.3 removes EventAI together with the flags --ai-model and --ai-option. A server started with either of them refuses to start: it prints its usage and exits with code 1, logging failed to execute command with the error unknown flag: --ai-model. Remove both flags from the command line before you upgrade.

License#

If you are running EventSourcingDB with a commercial license, you must provide it either as a file (--license-file) or directly as a string (--license-string).

Without a license, the server runs in free mode with all features enabled but is limited to storing a maximum of 25,000 events.

Diagnostic Tools#

You can use the diagnostics subcommand to connect to a running EventSourcingDB server and retrieve system information. This is especially useful for monitoring, debugging, or health checks.

./eventsourcingdb diagnostics --url http://localhost:3000 --api-token <TOKEN>

This command returns the version and the system of both the CLI and the server, the details of the license, and the options the server runs with.

Added in 1.3It asks the server for its diagnosis through the API, with POST /api/v2/system/diagnose. A server of an earlier version has no such route, so against it, the command reports that the version of the server apparently does not match the version of this CLI. Use the CLI of the server's version there.

Version Information#

To display the installed version of EventSourcingDB, run:

./eventsourcingdb version

This prints the current version number and build metadata.