The dev CLI - Aperium Docs

dev is the Aperium developer and operator command line, provided by the devkit app. It drives the local stack, runs the validation gates, manages infrastructure and the database, scaffolds and validates plugins, and hosts a range of operational helpers. Run it through uv for one-off commands:

uv run dev --help
uv run dev check

For an editable command on your shell PATH, sync the workspace and activate the virtualenv:

uv sync --all-packages --all-groups
source .venv/bin/activate
dev --help

Without activating the virtualenv, call .venv/bin/dev.

Command groups

Run uv run dev --help for the authoritative, always-current list. The groups you’ll reach for most:

Group	What it does
`run`	Run the local stack (infra + API + worker + UI).
`check`	The validation gate suite (Ruff, format, Pyright, import-linter, architecture and charter checks).
`infra`	Start / stop local Compose infrastructure.
`db`	Database migrations and maintenance.
`install`	Sync the Python workspace and install UI dependencies.
`plugins`	Scaffold, validate, smoke-load, and record plugins.
`test`	Run the test suites.
`codegen`	Generate code artifacts (contract schemas, types).
`credentials`	Local credential-vault helpers.
`evals`	Run the deterministic runtime eval harness.
`ops`	Read-only operational helpers (e.g. deployment-binding enumeration).
`version`	Print workspace package versions.
`dev`	Local dev-identity overrides for testing.

Additional groups exist for narrower or platform-specific tasks. Prefer uv run dev <group> --help over memorizing the surface — the CLI is the source of truth.

run

Runs the local development stack: local infra via compose.yml, then aperium-api and aperium-worker, then the selected UI’s dev server.

uv run dev run                        # default UI + managed local infra
uv run dev run --overlay relativity   # a registered UI overlay (-o)
uv run dev run --external-infra       # app processes only, against infra you started (-x)
uv run dev run --mock                 # serve integrations from the in-process mock world

Flag	Effect
`--overlay`, `-o`	Run a registered UI by name (see `[tool.aperium.uis.<name>]`). Defaults to the project’s `default-ui`, or the sole registered UI.
`--external-infra`, `-x`	Use existing PostgreSQL / Redis / Temporal / Phoenix instead of starting local Compose infra.
`--mock`	Serve odoo / slack / github / google from the in-process mock world; implies dev fixtures.

check

The default gate suite: Ruff, formatting, Pyright, import-linter, package-dependency checks, architecture-hygiene checks, unit-charter checks, and agent-context health checks.

uv run dev check                 # run everything
uv run dev check --only python   # one group (e.g. python | frontend)
uv run dev check --jobs 4        # cap concurrency (default: CPU count)

Lint and check commands operate on the monorepo structure by design.

infra

uv run dev infra up      # start local backing services (PostgreSQL + profiles)
uv run dev infra down    # stop containers, preserving data volumes

db

uv run dev db migrate                       # apply migrations
uv run dev db oauth-callbacks reconcile     # preview OAuth callback repairs (dry-run default)

db oauth-callbacks reconcile is dry-run by default; applying updates requires an explicit confirmation env var plus --apply.

plugins

The plugin authoring surface — covered end to end in Build a plugin.

uv run dev plugins new <slug>       # scaffold a new plugin
uv run dev plugins validate <slug>  # validate one plugin's manifest
uv run dev plugins smoke            # smoke-load all shipped plugin manifests
uv run dev plugins record <slug>    # record VCR cassettes for a plugin's vcr-marked tests

test

uv run dev test          # the default suite
uv run dev test fast     # fast Python tests only

Project awareness

Runtime commands (dev run, dev install) discover the calling project by walking upward for the nearest pyproject.toml carrying a [tool.aperium] block:

[tool.aperium]
default-ui = "core"          # required when more than one UI is registered

[tool.aperium.uis.core]
path = "ui"                  # UI package path, relative to project root

The same CLI therefore runs from the Aperium monorepo and from downstream product repos that depend on devkit and want to drive the same local stack. A project with a single registered UI may omit default-ui. Lint and check commands remain monorepo-only.

Dev identity overrides

dev dev writes a small, gitignored, per-developer JSON file that overrides the dev-fixtures identity the API and SPA use for local testing. Production deploys ship with dev fixtures disabled, so the file and its endpoints are never read there.

uv run dev dev whoami                # show the resolved identity
uv run dev dev as member             # switch to a named role preset
uv run dev dev set --role admin --email me@example.com
uv run dev dev reset                 # remove the override file

​Command groups

​run

​check

​infra

​db

​plugins

​test

​Project awareness

​Dev identity overrides

Command groups

run

check

infra

db

plugins

test

Project awareness

Dev identity overrides