# 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: ```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. 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 *(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**. 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](/docs/eventsourcingdb/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**. ### 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 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: ```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 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: ```shell ./eventsourcingdb version ``` This prints the **current version number** and **build metadata**.