EverOS/docs/cli.md

CLI

The everos command-line entry point covers setup and operations — generate a starter .env (init), run the HTTP API server (server start), and operate the md → LanceDB index queue (cascade). Hot-path business (/add /flush /search /get) is the HTTP API, not the CLI.

CLI commands run in-process — they call into the service/ / infrastructure layers directly rather than the HTTP loopback.

Installation

The script is exposed via pyproject.toml:

[project.scripts]
everos = "everos.entrypoints.cli.main:app"

After uv sync (or pip install -e .) the everos command resolves to src/everos/entrypoints/cli/main.py, a Typer app.

Subcommand layout

everos
├── init                            Generate a starter .env from the packaged template
├── server
│   └── start                       Start the HTTP API server (uvicorn)
└── cascade                         Inspect / operate the md → LanceDB sync queue
    ├── status                      Queue / LSN summary
    ├── sync                        Drain the queue now (force md → LanceDB)
    └── fix                         List failed rows / re-enqueue retryable ones

Each subcommand lives in its own module under entrypoints/cli/commands/ and is registered in cli/main.py. The CLI is intentionally small — hot-path business (/add /flush /search /get) is the HTTP API, not the CLI; the CLI covers setup (init), running the server, and index ops (cascade). There is no reindex command — rebuild by deleting <root>/.index/lancedb and restarting, or run everos cascade sync.

everos server start

Wraps uvicorn to launch the FastAPI app from entrypoints/api/app.py in factory mode.

everos server start \
    --host 127.0.0.1 \
    --port 8000 \
    --log-level info \
    --env-file .env

Flag	Env var	Default
--host	EVEROS_API__HOST	127.0.0.1 (loopback only; binding 0.0.0.0 logs a warning — EverOS ships no auth)
--port	EVEROS_API__PORT	8000
--log-level	EVEROS_LOG_LEVEL	INFO
--env-file	—	searched: ./.env → $XDG_CONFIG_HOME/everos/.env → ~/.everos/.env
--reload	—	off (use in development)

Lifespan startup wires the storage backends (SQLite engine + LanceDB connection) on app boot; see entrypoints/api/lifespans/.

Configuration via env vars

Both CLI and HTTP server read configuration from pydantic-settings:

Env var	Settings field
EVEROS_MEMORY__ROOT	Settings.memory.root (memory-root path)
EVEROS_MEMORY__TIMEZONE	Settings.memory.timezone (e.g. Asia/Shanghai)
EVEROS_SQLITE__BUSY_TIMEOUT_MS	Settings.sqlite.busy_timeout_ms
EVEROS_LANCEDB__READ_CONSISTENCY_SECONDS	Settings.lancedb.read_consistency_seconds

Pattern: EVEROS_<SECTION>__<KEY> (double underscore = nesting). See config/settings.py.

Logging

configure_logging runs at CLI startup and configures structlog with the resolved log level. All in-process logs (CLI command bodies + service / infra layers) flow through the same handler.

everos server start --log-level debug   # see all sql / lance traffic

API ↔ CLI division of labour

Responsibility	API	CLI
Hot-path business (/add /flush /search /get)	✅	— (HTTP only)
Setup (generate .env)	—	everos init
Run the server	—	everos server start
Index ops (drain / inspect / fix the cascade queue)	—	everos cascade {status,sync,fix}
Health probe	GET /health	(use HTTP)
Metrics scrape	GET /metrics	(use HTTP)

The CLI is the shell-friendly surface for ops + scripting; the HTTP API is the process-friendly surface for clients (web UIs, agents, automation).

See also

• architecture.md — DDD layering between entrypoints / service / memory / infra
• entrypoints/cli/main.py
• entrypoints/cli/commands/server.py