# 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.3)* 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: ```shell ./eventsourcingdb --help ``` To view **help for a specific command**, append `--help` to that command, for example: ```shell ./eventsourcingdb run --help ``` ## Starting the Server You can **start an EventSourcingDB instance** using the `run` subcommand: ```shell ./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-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.3)* To 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 Signing *(Added 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.2)* 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`. *(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](/docs/eventsourcingdb/v1.2/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 *(Changed 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: ```shell ./eventsourcingdb run [...] --with-ui --ai-model openai-gpt-4o --ai-option 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](/docs/eventsourcingdb/v1.2/management-ui#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**. ```shell ./eventsourcingdb diagnostics --url http://localhost:3000 --api-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 Server *(Removed in 1.3)* The CLI includes an **embedded version of the official documentation**. You can start it locally using: ```shell ./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 Generator *(Removed 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: ```shell ./eventsourcingdb version ``` This prints the **current version number** and **build metadata**.