CLI Overview
This guide provides a high-level overview of the EventSourcingDB CLI. It explains how to start the database, access built-in tooling, and configure typical runtime options such as ports, HTTPS certificates, and data directories.
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 various subcommands such as run, diagnostics, generate, docs, and others. 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. - Exactly one of
--data-directoryand--data-directory-temporary. - With HTTPS enabled, which is the default, both
--https-certificate-fileand--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 (/api/v1/ping) and the OpenAPI definition (/.well-known/openapi). You can choose any string, but for production deployments, it should be a randomly generated, high-entropy value.
Changed in 1.3
Access Control
There is currently no role-based access model. Anyone with the token has full access. We recommend using a token with at least 32 characters, consisting 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.
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.
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.
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.
EventAI IntegrationChanged in 1.3#
If you want to use EventAI in the management UI, which generates EventQL queries from natural language, configure its model with --ai-model and its options with --ai-option, each option as key=value. EventAI is disabled by default and becomes available only with both flags and the management UI enabled. The only model is OpenAI's GPT-4o, with the identifier openai-gpt-4o, which requires your OpenAI API token as the option token; without it, the server does not start:
./eventsourcingdb run [...] --with-ui --ai-model openai-gpt-4o --ai-option token=<OPENAI_API_TOKEN>
EventAI sends your prompts, the conversation, and the event types with their schemas to OpenAI, but no data of your events. For how to use it, see Using EventAI.
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.
Local Documentation ServerRemoved in 1.3#
The CLI includes an embedded version of the official documentation. You can start it locally using:
./eventsourcingdb docs
By default, it runs on port 4000, but you can change this using the --http-port flag. If you're running both the documentation server and the HTTPS API locally, make sure they use different ports to avoid conflicts.
Event GeneratorRemoved in 1.3#
For testing purposes, the generate subcommand can create synthetic event data for a specified domain. You must provide a domain name (--domain-name) and define the time range using --start-time and --end-time. The format must follow the RFC 3339 standard (e.g. 2025-03-27T10:57:05Z).
The only domain is library, which requires four options, each passed as key=value with a --domain-option flag of its own: maxNumberOfBooks and maxNumberOfReaders, the maximum numbers of books and readers to generate, and initialNumberOfBooks and initialNumberOfReaders, the numbers of books and readers the library starts with.
Optionally, you can provide a --seed value to make the generated data reproducible.
The command writes the event schemas of the domain and the generated events to the standard output, one JSON object per line. This tool is useful for load testing, integration testing, or simulating realistic data flows during development.
Version Information#
To display the installed version of EventSourcingDB, run:
./eventsourcingdb version
This prints the current version number and build metadata.