CLI (semvec)

The semvec command ships with the [api] extra and wraps uvicorn to run the REST API. Install it via:

pip install "semvec[api]"

Commands

semvec serve

Start the Semvec REST API server.

semvec serve [--host HOST] [--port PORT] [--reload] [--log-level LEVEL]

Flag	Type	Default	Description
--host	str	0.0.0.0	Bind address. Use 127.0.0.1 to restrict to localhost.
--port	int	8080	TCP port.
--reload	bool flag	off	Enable uvicorn auto-reload on source change. Development only.
--log-level	critical / error / warning / info / debug	info	Log level for both uvicorn and the semvec application.

The server loads semvec.api:create_app via uvicorn's --factory mode, so every process creates its own SessionManager, ClusterManager, etc. (state is in-memory and therefore per-worker — see the REST API for the SQLite metadata schema used for cross-worker persistence).

Environment variables read at start-up

Variable	Default	Purpose
DATABASE_URL	sqlite:///semvec.db	SQLAlchemy URL for the session / cluster / audit metadata store.
CORS_ORIGINS	empty (no cross-origin access)	Comma-separated list of allowed origins, e.g. https://app.example.com,http://localhost:5173.
SEMVEC_LICENSE_KEY	—	Ed25519-signed license JWT (Pro / Enterprise features).
SEMVEC_ALLOW_ANONYMOUS	unset	Set to 1 to bypass license verification — development only, every request is treated as anonymous community-tier.
METRICS_USER / METRICS_PASSWORD	—	Basic Auth for the /metrics endpoint. Must both be set to enable the endpoint.

Examples

Local development

export SEMVEC_ALLOW_ANONYMOUS=1
export DATABASE_URL="sqlite:///dev.db"
semvec serve --host 127.0.0.1 --port 8080 --reload --log-level debug

Production behind a reverse proxy

export DATABASE_URL="postgresql://semvec:pass@db/semvec"
export CORS_ORIGINS="https://app.example.com"
export METRICS_USER="prom"
export METRICS_PASSWORD="$(cat /run/secrets/metrics_password)"
semvec serve --host 0.0.0.0 --port 8080 --log-level info

Behind nginx / an ALB, the server trusts the X-Forwarded-For and X-Real-IP headers for client-IP resolution (used by the rate limiter and the audit log).

Programmatic start (without the CLI)

python -m uvicorn semvec.api:create_app --factory --host 0.0.0.0 --port 8080

Same effect, handy when you want to wire the factory into a larger ASGI app (e.g. mounted under a prefix).