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¶
The 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:
To view help for a specific command, append --help to that command, for example:
Starting the Server¶
You can start an EventSourcingDB instance using the run subcommand:
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. If these are not provided, the CLI will exit with an error. Refer to the CLI help output (eventsourcingdb run --help) for a complete list.
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.
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¶
To secure the API, an API token must be provided using the --api-token flag. This token is required for all routes except /ping. You can choose any string, but for production deployments, it should be a randomly generated, high-entropy value.
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.
Event Signing¶
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.
When 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.
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 Integration¶
If you want to use EventAI (e.g. to generate EventQL queries from natural language) in the UI, you must configure the model and related options using --ai-model and --ai-option.
EventAI is disabled by default and becomes available only if both parameters are explicitly configured. To enable EventAI with OpenAI's GPT-4o model, use the model identifier openai-gpt-4o and provide your OpenAI API token using the token option.
For complete configuration instructions, security considerations, privacy implications, and troubleshooting, see Configuring 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.
This command returns details such as storage usage, active streams, and system metrics.
Local Documentation Server¶
The CLI includes an embedded version of the official documentation. You can start it locally using:
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 Generator¶
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).
Depending on the domain chosen, you may have to pass additional options using the --domain-option flag.
Optionally, you can provide a --seed value to make the generated data reproducible.
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:
This prints the current version number and build metadata.