CLI Reference

The eidetica binary provides a server and management commands for inspecting and operating on Eidetica instances.

Commands

serve (default)

Starts the Eidetica server with HTTP and sync endpoints.

Running eidetica with no subcommand is equivalent to eidetica serve. This default is likely to change in the future. Do not run serve alongside daemon on the same SQLite backend.

eidetica serve [OPTIONS]

health

Checks the health of a running Eidetica server by querying its /health endpoint.

eidetica health [URL] [OPTIONS]

Both http:// and https:// URLs are supported. If the URL doesn’t already end with /health, it is appended automatically.

Exits with code 0 on success, code 1 on failure.

info

Displays instance information: device ID, storage backend, user count, and database count.

eidetica info [OPTIONS]

Example output:

Device ID:   a1b2c3d4-...
Backend:     sqlite (./eidetica.db)
Users:       2
Databases:   5

daemon init

Initialises a fresh Eidetica instance on the chosen backend with an initial admin user. The first user created on an instance is automatically granted Admin on the system databases. Fails if the backend already has an instance on it.

eidetica daemon [BACKEND OPTIONS] init --username <NAME> [--password <PASS> | --passwordless]

--username has no default: operators must spell it out so no static credential ships by accident. --passwordless is intentionally a separate opt-in (rather than just leaving --password unset) — pick it only for embedded or single-user development; production deployments should set a password.

Examples:

# Interactive password prompt:
eidetica daemon --data-dir /var/lib/eidetica init --username ops

# Non-interactive (e.g. CI provisioning):
EIDETICA_ADMIN_PASSWORD=… eidetica daemon --data-dir /var/lib/eidetica init --username ops

# Embedded / single-user dev workflow:
eidetica daemon --data-dir ~/.local/share/eidetica init --username me --passwordless

Backend options (--backend, --data-dir, --postgres-url) go before the init subcommand and are shared with daemon (see below).

daemon

Runs the Eidetica service daemon against an already-initialised backend. Fails with a pointer at daemon init if the backend hasn’t been initialised yet. Multiple client processes can connect to the running daemon over the Unix socket to share the same backend storage.

eidetica daemon [OPTIONS]

The daemon runs until interrupted with SIGINT or SIGTERM. Clients connect using Instance::connect("unix://..."). See Service (Daemon) Mode for full documentation.

db list

Lists all user-created databases with their root IDs and tip counts. System databases are excluded.

eidetica db list [OPTIONS]

Example output:

ROOT ID         TIPS
abc123def456    5
xyz789uvw012    2

Global Flags

The --json flag works with info and db list.

Storage Backends

Environment Variables

Command-line flags take precedence over environment variables.

Examples

# Start server with defaults (sqlite backend, port 5942)
eidetica

# Start with PostgreSQL backend on a custom port
eidetica serve --port 8080 --backend postgres \
  --postgres-url "postgresql://user:pass@host/db"

# Check health of a running server
eidetica health

# Show instance info as JSON
eidetica info --json

# List databases from a specific data directory
eidetica db list --data-dir /var/lib/eidetica

# Start a daemon for shared multi-process access
install -d -m 0700 "$XDG_RUNTIME_DIR/eidetica"
eidetica daemon --socket "$XDG_RUNTIME_DIR/eidetica/service.sock"

db reset-local-verification (offline trust reset)

Before upgrading an existing instance to new delegated-authorization verification rules, stop the daemon/server and all writers and readers, back up the database, then run the reset with the same backend configuration as the instance:

eidetica db reset-local-verification --backend sqlite --data-dir /var/lib/eidetica --confirm
# Or: --backend inmemory --data-dir <directory containing eidetica.json>
# Or: --backend postgres --postgres-url <instance connection URL>

The command does not run during startup or schema migration. Skipping it can leave old Verified labels trusted under the new rules. It resets all local statuses (Verified and Failed included) to Unverified, discards derived and incomplete Store-state namespaces, and keeps every immutable Entry and authoritative Store state. It does not verify entries itself. Start the new version only after the command succeeds; explicitly run ordinary Database::verify() for each database (including dependencies) or let normal verification on access/sync rebuild trust before relying on reads. Verification is prefix-closed: until ancestors verify, descendants remain Unverified. If any reset step fails, leave the service stopped, diagnose and retry the command; do not trust the old status labels. An in-memory persistence file must exist and parse successfully; a missing or corrupt file is never treated as an empty instance by this command.

SQLite and PostgreSQL commit status and cache changes in one transaction. The persisted in-memory backend writes a replacement JSON snapshot by atomic rename on POSIX; if writing fails before rename, the old file remains in place. Run the command with no other process or API user of the backend: the normal online clear_derived_store_state retains a generation for live readers, whereas the trust reset deliberately drops it. The in-memory JSON persistence path has no cross-process ownership lock. On platforms without atomic replacement rename, take an offline backup and verify the reopened file before starting the service.