Reference

CLI flags

The eideticd binary doubles as a service manager and ops tool. Most flags run a single one-shot action and exit; the rest control the long-running daemon.

Service lifecycle

-install

Registers eideticd as a login-time service: launchd (works.eidetic.eideticd) on macOS, systemd-user (eideticd.service) on Linux. Binary path resolved via os.Executable() + EvalSymlinks so Homebrew shims resolve correctly. (v0.0.29+)

eideticd -install
# Daemon starts and passes /healthz within 1 second

-uninstall

Stops the daemon, removes the launchd plist or systemd-user unit, then prompts to delete <dataDir> interactively. (v0.0.44+)

eideticd -uninstall          # interactive prompt before deleting data
eideticd -uninstall -purge   # unattended: skip prompt, delete <dataDir>

-version

Prints the daemon's version and exits. Injected at build time via -ldflags "-X main.Version=$(git describe ...)".

eideticd -version
# → eideticd 0.0.45

Observability

-stats

Prints engram count, per-surface breakdown, oldest/newest timestamps, DB file size, and P95 retrieval latency; then exits. Works whether the daemon is running or not (opens the SQLite file directly in read-only mode). (v0.0.26+)

v0.0.33+ adds a "cloud sync" block when sync-state.json exists. v0.0.37+ adds an upgrade hint when a newer release is cached.

eideticd --stats
# → eideticd v0.0.45 — engram statistics
# →   engrams:    278561
# →     claude_code          274203
# →     cursor                 4135
# →     cowork                  223
# →   oldest:     2026-03-01
# →   newest:     2026-05-20
# →   db size:    3.3 GB
# →   P95 fetch:  0.27 ms
# →
# →   cloud sync:
# →     last sync:  2026-05-20 09:00:00
# →     last key:   engrams/macbook-m2/engrams-1779235200000.db
# →     last size:  3.3 MB

Cloud sync

Cloud sync requires ~/.eidetic/sync.json. See the Pro tier docs for managed setup, or bring your own R2.

-sync-now

Upload engrams.db immediately and exit. Useful for manual one-shot backup or post-export before machine wipe. (v0.0.24+)

eideticd --sync-now

-restore

Downloads the most recent R2 backup for the configured device and atomically replaces the local engrams.db. Previous file is saved to engrams.db.bak. Runs before store.Open so there is no write-lock conflict. (v0.0.32+)

eideticd --restore
# ✓ Downloaded 3.3 GB engrams.db from cloud backup
#   key: engrams/macbook-m2/engrams-1748300000000.db
#   previous db saved to ~/.eidetic/engrams.db.bak
#   restart eideticd to use the restored database

-check

Validates sync.json, pings the Worker's /healthz with the configured api_key, and reports last sync state. Exits 0 if healthy, 1 if config is missing or Worker unreachable. (v0.0.34+)

eideticd --check
# → worker: ✓ reachable (200 OK)
# → last sync: 2026-05-20 09:00 (4m ago)
# → status: ✓ sync healthy

-backups

Prints the last 10 cloud backups (timestamp, R2 key, MB). Ring buffer is appended after every successful upload. Falls back to single LastSync row for pre-v0.0.36 state files. (v0.0.36+)

eideticd --backups

Listeners

-bridge <addr>

Starts a second TCP listener alongside the primary UDS server. Both share the same *store.Store (one SQLite write path, no lock contention). Used for the web dashboard, or remote access via Cloudflare tunnel. (v0.0.31+)

Bridge auth is always-on — the bridge listener generates its own Bearer token at startup (independent of the primary EIDETIC_AUTH flag). Token written to ~/.eidetic/bridge-token (0600). Rotates every restart. CORS headers added on bridge responses only.

eideticd -bridge :8421
# Then open https://eidetic.works/dashboard and paste
# http://127.0.0.1:8421 + the token from ~/.eidetic/bridge-token

-auth

Enables Bearer-token auth on the primary UDS listener (off by default). Equivalent to EIDETIC_AUTH=1 env var. /healthz stays open; everything else requires Authorization: Bearer <token>. Token at <dataDir>/auth-token, rotates every restart. (v0.0.9+)

Environment variables

Var	Effect
`EIDETIC_DATA_DIR`	Override the data root (default `~/.eidetic/`).
`EIDETIC_TCP=1`	Listen on `127.0.0.1:9876` instead of (or in addition to) the UDS. Loopback only.
`EIDETIC_AUTH=1`	Enable Bearer-token auth (same as `-auth` flag).
`EIDETIC_AUTH_TOKEN`	Override the auto-discovered token in MCP bridge clients.
`EIDETIC_PING=0`	Opt out of the post-install ping from the `pip install eidetic-mcp` hook.

eideticd-compliance

Separate binary for per-surface data retention. Reads ~/.eidetic/retention-policy.json, purges rows older than configured day thresholds per surface, appends audit lines to ~/.eidetic/compliance.log. Designed to run via cron / launchd timer / systemd timer — runs one pass and exits. Zero impact on daemon uptime — operates against the same engrams.db via the existing writer pool. (v0.0.25+)

# Dry-run: report what would be deleted, change nothing
eideticd-compliance --dry-run

# Live: enforce the policy
eideticd-compliance

Example policy at scripts/retention-policy.example.json in the source repo: claude_code: 30d, cursor: 90d, cowork: 365d.