> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aperium.apps.hillspire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The dev CLI

> Reference for devkit — the dev command that drives the local Aperium stack, checks, and tooling.

`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:

```bash theme={null}
uv run dev --help
uv run dev check
```

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

```bash theme={null}
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.                                                          |

<Info>
  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.
</Info>

## run

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

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
uv run dev infra up      # start local backing services (PostgreSQL + profiles)
uv run dev infra down    # stop containers, preserving data volumes
```

## db

```bash theme={null}
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](/develop/build-a-plugin).

```bash theme={null}
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

```bash theme={null}
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:

```toml theme={null}
[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.

```bash theme={null}
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
```