Alembic · Visual Course

Checking your setup with alembic doctor

Probe the local toolchain and external services before running expensive commands.

Read the plain version, or open the technical layer on any section.

Why probe first

Many Alembic commands depend on Node, pnpm, git, the Higgsfield CLI, and a local LLM gateway. Rather than discovering a missing tool halfway through a long run, doctor surfaces problems up front.

Each check returns ok, warn, or fail. A warning means the command can still run in offline or degraded mode; a fail means something required is missing.

Think of it like… the instrument panel in a car: green lights are reassuring, yellow lights mean pay attention, red lights mean stop.

Under the hood

runDoctor checks process.version, runs pnpm --version, git --version, and which higgsfield. It verifies the data directory is reachable and probes http://127.0.0.1:8317/v1/models when not forced offline. The bearer token is read from ALEMBIC_CLIPROXY_TOKEN when present. Results are returned as a typed DoctorReport.

In one picture

Green checks pass, yellow checks are warnings, red checks block the related workflow.

In the code

# human-readable report
alembic doctor

# JSON report for CI
alembic doctor --json

# probe the gateway even when ALEMBIC_OFFLINE is set
alembic doctor --force

Implementation notes

The --force flag is useful in CI: it makes the gateway probe run even if ALEMBIC_OFFLINE would normally skip it. The JSON shape is stable and can be consumed by dashboards or alerts.

Try it

Run alembic doctor on your machine. If any check is red or yellow, read the message and fix the dependency. Re-run until you are satisfied with the summary line.

Integration idea: Add alembic doctor --json as a CI step and fail the job when fail > 0.