Command reference
Every make target, its description, and whether CI runs it.
Both columns are read from source — the descriptions from the Make interface’s own ##
comments, the CI column from make invocations in the workflows — so this page
cannot drift from either. make dev-docs-verify fails the build if it does.
✅ means a workflow invokes that target by name. A blank cell is not “never runs in CI” — prerequisite targets run through their named parent. The runs: note on a row lists what each parent pulls in.
Routine local evidence is make verify BASE=<base>. It selects affected checks
from the same impact policy as CI. Use make verify SCOPE=all only for a comprehensive audit.
General
| Target | CI | What it does |
|---|---|---|
make help | List targets |
Agent / worktree harness
| Target | CI | What it does |
|---|---|---|
make agent-start | register this worktree and its seams (TASK=… CLAIMS=a,b; optional DEPENDS_ON=task) | |
make agent-status | list tool-neutral agent sessions across every worktree | |
make agent-renew | renew this worktree’s claim lease (AGENT_LEASE_HOURS=4) | |
make agent-prune | remove expired entries from the shared agent registry | |
make agent-stop | release this worktree’s task and shared-output claims | |
make agent-env | show this worktree’s isolated ports, database, compose project, and artifact path | |
make agent-baseline | share one cached make verify SCOPE=all result per clean commit/toolchain | |
make agent-verify | compatibility alias for make verify runs: verify | |
make test-affected | run unit tests related to changed files during editing (not final evidence) | |
make agent-worktree | create, claim, and bootstrap a sibling worktree (TOPIC=… CLAIMS=…; BASE/DEPENDS_ON for stacks) | |
make agent-gc | audit worktrees; APPLY=1 retires only exact clean merged PR heads | |
make agent-reap | list processes running in a worktree (WORKTREE=path, or ORPHANS=1 for deleted ones); APPLY=1 stops them | |
make dev-watch | watch local resources, your PRs and agent lanes; prints only when something needs attention | |
make bootstrap | build the Rust worker and prepare frontend, isolated directories, and dev identity | |
make doctor | verify toolchain and Docker readiness; report worktrees, ports, caches, and artifacts | |
make agent-harness-test | ✅ | regression-test coordination, worktree isolation, and shared-output claims runs: agent-assets-verify |
make agent-assets-verify | verify the curated skill catalog and agent adapters agree | |
make compose-verify | ✅ | verify Traefik, database wiring, and pinned release images |
make release-verify | ✅ | verify release, CI acquisition, Android, and publication policy |
make release-notes-preview | generate validated release notes (TAG required; optional PREVIOUS_TAG and OUTPUT) | |
make docs-release-gate | fail a release whose user-facing changes have no docs change (TAG, PREVIOUS_TAG required; run after release-notes-preview, #1682) | |
make backup-restore-verify | isolated SQLite backup, destructive replacement, restore, and state validation | |
make backup-restore-drill | SQLite + Docker-backed Postgres backup/restore drills runs: backup-restore-verify | |
make graph | build the local Graphify index in graphify-out/ (never committed; needs graphifyy, see docs/agents/graphify.md) |
Proportional local verification
| Target | CI | What it does |
|---|---|---|
make verify | run affected local evidence; SCOPE=all runs the comprehensive repository audit |
Explicit complete audit
| Target | CI | What it does |
|---|---|---|
make check-static | repository contracts without the unit-test suite (CI runs this once beside test lanes) runs: rust-check fmt shellcheck privacy-verify observability-verify vet platform-vet tags-verify vet-tags lint agent-harness-test compose-verify release-verify go-race-verify | |
make observability-verify | ✅ | validate the metric manifest, Prometheus rules, and Grafana provisioning (needs Docker and jq) |
make rust-check | ✅ | format, lint, build, and test the required Rust image worker runs: rust-test-worker |
make rust-test-worker | build the debug Rust image worker required by Go unit tests | |
make rust-audit | check Rust advisories, licences, and dependency sources (needs cargo-deny) | |
make rust-fuzz | fuzz the bounded Rust image protocol/decoder; optional FUZZ_SECONDS (needs nightly + cargo-fuzz) | |
make fmt | ✅ | gofmt -l (fails if any file needs formatting) |
make shellcheck | ✅ | shellcheck every repository shell script |
make privacy-verify | ✅ | captured private fixture literals and real media titles must not re-enter the tracked tree runs: demo-titles-verify |
make vet | ✅ | go vet |
make platform-vet | go vet the opposite Linux/macOS target to catch platform-only compile drift | |
make vet-tags | ✅ | go vet over custom-tagged sources |
make tags-verify | ✅ | the Makefile’s TAGS list matches every //go:build tag in the tree, both ways |
make lint | ✅ | golangci-lint v2 (run via go run so no global install needed) |
make vuln | ✅ | govulncheck: known vulnerabilities reachable from Loomarr code, stdlib included |
make scan-scale | ✅ | library scanner’s scale guard over a 33k-file library (about a minute) |
make deadcode | functions no ./cmd binary reaches, per package (report only; not a PR gate) | |
make deadcode-baseline | rewrite the committed deadcode baseline the monthly report compares against | |
make test | ✅ | unit tests; unsharded runs include Rust worker and eval contracts (never network — §19) |
make go-shard-verify | ✅ | Go test lanes must cover every package within their latency and balance budgets |
make go-race-weights | regenerate the race-lane package weights from hosted merge-group runs (RUNS=“run-id …”) | |
make go-race-verify | ✅ | every -race opt-out (scripts/go-race-policy.sh RACE_OFF) must be a real package |
make test-ffmpeg | ✅ | media tests that EXECUTE ffmpeg (needs ffmpeg+ffprobe; not in comprehensive verification) |
make research-verify | compile the archived filler research module against its pinned core (all build tags; not a CI gate) | |
make eval-contract | ✅ | hermetic semantic-evaluation contracts; never contacts a model, Library, or TMDB |
make eval | semantic eval: real intents → real LLM → scored (needs LLM_*/LOOMARR_LIBRARY_DB/TMDB_API_KEY; NOT in the hermetic gate) | |
make eval-cert | certify exact intents and mandatory scheduled viewer outcomes; fails closed and writes a scorecard | |
make eval-planner-cert | compare one model against the frozen planner corpus; explicit, inference-spending, non-CI | |
make eval-planner-smoke | replay one frozen base Intent per planner family; explicit, inference-spending, non-CI | |
make eval-query-expansion-diagnostic-dry-run | preflight the ten-case Gemini query diagnostic without inference | |
make eval-query-expansion-diagnostic | run the authorized ten-case Gemini query diagnostic (paid/manual) | |
make planner-tool-diagnostic | probe the exact post-catalog-result model turn; explicit, inference-spending, non-CI | |
make channel-recommend-cert | certify inert channel concepts on the frozen recommendation corpus; explicit, inference-spending, non-CI | |
make channel-recommend-cert-dry-run | emit the provider-free recommendation certification contract; no inference | |
make channel-recommend-diagnostic | diagnose recommendation JSON transport on the disjoint development corpus; explicit, inference-spending, non-CI | |
make channel-recommend-compare | compare channel-recommendation scorecards without inference | |
make eval-planner-compare | compare two or more frozen planner scorecards without inference | |
make planner-reference-host | bind one planner scorecard to exact local artifact and reference-host evidence; no inference | |
make eval-matrix | explicitly certify local + OpenRouter generation sequentially (manual, resource-heavy) | |
make filler-eval-contract | hermetic filler-admission corpus and selective-risk contracts | |
make filler-temporal-truth-select | select the private 48-case truth-review sample from frozen history without inference | |
make filler-temporal-truth-prepare | build the sealed complete-span 48-case evidence set without inference | |
make filler-temporal-assess-ollama | assess the sealed temporal challenge with a digest-pinned local model | |
make filler-temporal-compare | compare two independent temporal assessment sets without inference | |
make filler-temporal-select | derive an immutable stratified temporal calibration selection without inference | |
make filler-temporal-assess-openrouter | run a bounded paid temporal calibration on an exact snapshotted route | |
make filler-temporal-calibration-report | compare one hosted temporal result with its two bound local assessments | |
make filler-corpus-commons | freeze bounded Commons pilot and full-inventory artifacts | |
make filler-corpus-cdc | freeze bounded CDC pilot and full-inventory artifacts | |
make filler-corpus-loc | freeze bounded LOC pilot and full-inventory artifacts | |
make filler-corpus-met | freeze a bounded metadata-only Met Museum inventory | |
make filler-corpus-met-rights-propose | pre-screen frozen Met rights metadata without granting authority | |
make filler-corpus-met-rights-attestation | prepare one pending, digest-bound Met rights attestation | |
make filler-corpus-met-rights-complete | expand one accepted Met attestation into item-bound review rows | |
make filler-corpus-nasa | freeze bounded NASA pilot and full-inventory artifacts | |
make filler-corpus-pilot | lock the qualified metadata-only filler rights-yield pilot | |
make filler-corpus-pilot-rights-review | prepare the inert five-lane pilot review packet | |
make filler-corpus-pilot-rights-lock | lock completed pilot review into a non-authorizing yield report | |
make filler-corpus-archive | freeze a bounded rights-filtered Archive.org corpus inventory | |
make filler-corpus-inventory | combine strict source inventories for mixed-authority rights review | |
make filler-corpus-direct | freeze an authored local cohort with rights and provenance evidence | |
make filler-corpus-prepare | build an unlabeled corpus draft and bounded evidence packets | |
make filler-corpus-download | download only rights-approved corpus media under hard ceilings | |
make filler-visual-corpus-nomination-prepare | prepare four-field visual nomination review from approved media | |
make filler-visual-corpus-nomination-lock | lock reviewed visual nominations into a private corpus source root | |
make filler-corpus-rights-review | prepare an inert worksheet from a frozen filler inventory | |
make filler-corpus-rights-lock | validate completed rights review CSV into approval JSONL | |
make filler-corpus-lock | lock two blind filler-label batches into a certification manifest | |
make filler-media-integrity-prepare | prepare a label-free media-integrity challenge without inference | |
make filler-media-integrity-score | lock the private media-integrity comparison without inference | |
make filler-corpus-review | prepare one opaque randomized filler-label review batch | |
make filler-corpus-review-package | materialize one verified identity-blind reviewer evidence package | |
make filler-corpus-review-ollama | complete one blind package with a digest-pinned local reviewer | |
make filler-corpus-review-openrouter | complete one blind package through a bounded pinned hosted reviewer | |
make filler-openrouter-snapshot | lock OpenRouter capability, endpoint-price, and ZDR metadata | |
make filler-bakeoff-openrouter | capture a bounded label-blind OpenRouter prediction ledger (paid/manual) | |
make filler-bakeoff-ollama | capture a digest-pinned local filler prediction ledger (manual) | |
make filler-bakeoff-transcribe | capture digest-pinned shared filler transcripts (manual) | |
make filler-eval-cert | score captured filler decisions; never contacts a model or media source | |
make filler-release-readiness | produce the beta filler release GO/HOLD report without network access | |
make filler-household-cohort | bind the frozen beta filler seed to exact Ready playback outputs | |
make eval-planner-release-contract | verify the frozen production-intent release corpus without inference | |
make eval-planner-release-gate | replay release-critical intents 10x with latency gates; explicit, inference-spending, non-CI | |
make eval-planner-model-canary | run one bounded release-holdout trial for one configured planner model; explicit, inference-spending, non-CI | |
make eval-planner-model-finalist | repeat the model-canary cases 5x under an exact 1,000-call ceiling; explicit, inference-spending, non-CI |
Build / run
| Target | CI | What it does |
|---|---|---|
make build | build the cgo-free Go server and required Rust image worker runs: rust-build | |
make rust-build | build the required Rust image worker | |
make image-cert | ✅ | certify the Rust image worker; optional IMAGE_CERT_CORPUS=/absolute/path runs: rust-build |
make image-bench | ✅ | benchmark release-worker AVIF ladders; optional IMAGE_BENCH_RUNS/ROLES/REPORT runs: rust-build |
make playout-bench-corpus | generate the playout-bench corpus cache (keyed by recipe hash); run OUTSIDE any shared lock, then make playout-bench | |
make playout-bench | ✅ | run the cross-hardware playout bench on this host; PLAYOUT_BENCH_FAMILY/THRESHOLDS/HEIGHT/ACCEPT=1 (docs/contributing/playout-bench.md) |
make filler-encode-bench | VMAF-measure filler derivative encode levels for one hardware family; FILLER_ENCODE_BENCH_MASTERS/LEVELS required, optional FAMILY/LIMIT/FFMPEG/VMAF_THREADS (docs/design/filler-pipeline.md) | |
make image-parallelism-bench | ✅ | compare AVIF process/thread shapes at 2/4/8 CPUs (opt-in, Linux) runs: rust-build |
make dev | dev compose stack (external deps: tunarr-dev; portable Mac/Linux, CPU transcode) | |
make observability-dev | seed SQLite if needed, then start isolated local Prometheus + Grafana | |
make observability-dev-down | stop this worktree’s local observability stack (preserves its data) | |
make observability-dev-test | prove seeded Loomarr metrics and Grafana provisioning over real Docker + HTTP | |
make db-view | browse a copy of a database in CloudBeaver until Ctrl-C (FILE=backup.db, URL=postgres://…, ENGINE=postgres) | |
make test-sso | SSO against REAL Authelia + Authentik containers (requires Docker) | |
make dev-be | backend with live reload (Air) — rebuilds + restarts on Go/Rust changes | |
make rust-dev-build | build the debug Rust image worker the Go tests use (make dev-be runs a release one) | |
make dev-gpu | dev compose stack with NVIDIA transcode overlay (Linux + nvidia-container-toolkit) | |
make dev-fe | frontend with HMR on this worktree’s isolated port, proxying its backend | |
make seed | populate a dev store via the real domain paths (approval gate honored — AGENTS.md) | |
make demo-site | run the demo site from an image: VERSION= | |
make demo-site-down | stop the demo site and delete its data | |
make migration-rehearsal | boot IMAGE on a copy of the backup in BACKUP, with no network; run it where the backup lives (RECORD=1 records the pass a final tag needs) | |
make hardware-gate | has COMMIT passed the playout bench on Intel and NVIDIA? | |
make demo-library | serve the demo library’s Emby-compatible stand-in (generates its clips and art on first run) | |
make demo-titles-verify | no real media titles, brands or provider ids in seeds, fixtures or the demo catalogue (CI: privacy-verify, whenever ci-impact sees a scanned path) | |
make demo-seed | point this worktree’s backend at the running demo library and create the demo channels (idempotent) | |
make docs-capture | regenerate the docs screenshots from the demo seed (needs dev-be, dev-fe, demo-library, demo-seed) |
Store conformance (Phase 3/4)
| Target | CI | What it does |
|---|---|---|
make ensure-postgres-test-image | use cached Postgres and Ryuk images or pull them with bounded retries | |
make test-pg | ✅ | all real-Postgres integration suites (store, backend transition, app; testcontainers; requires Docker) runs: rust-dev-build ensure-postgres-test-image |
make test-db-lifecycle | certify Postgres conformance plus fresh-PG and SQLite→PG deployment lifecycles (Docker) runs: test-pg |
CI build-cache warming (#1570)
| Target | CI | What it does |
|---|---|---|
make go-cache-warm | ✅ | CI cache warming only: build one gate’s Go test binaries without running them (GO_CACHE_WARM names a race lane or postgres) |
OpenAPI (Phase 8)
| Target | CI | What it does |
|---|---|---|
make openapi | export api/openapi.yaml from the running definitions | |
make openapi-verify | ✅ | regenerated spec must match committed (CI red on drift) runs: openapi |
make ci-lint | ✅ | actionlint over .github/workflows — catches what YAML parsing cannot |
make retired-verify | ✅ | retired identifiers must not appear as live instructions (CI red on drift) |
Config docs (settings registry)
| Target | CI | What it does |
|---|---|---|
make config-docs | generate docs/reference/settings.md from the settings registry | |
make settings-keys | regenerate internal/platform/settings/keys_gen.go (typed setting handles) from the registry | |
make config-docs-verify | ✅ | regenerated config docs must match committed (CI red on drift) runs: config-docs |
Database reference (every table and column in plain words)
| Target | CI | What it does |
|---|---|---|
make db-docs | generate docs/reference/database.md from the migrations and internal/platform/store/schemadoc | |
make db-docs-verify | ✅ | regenerated database reference must match committed (CI red on drift) runs: db-docs |
Architecture map (docs/design/package-map.md)
| Target | CI | What it does |
|---|---|---|
make arch-docs | regenerate the package map and its area pages in docs/design/ from the code | |
make arch-docs-verify | ✅ | regenerated package map and area pages must match committed (CI red on drift) runs: arch-docs |
Dev docs (the command contract)
| Target | CI | What it does |
|---|---|---|
make dev-docs | generate docs/reference/make.md from this Makefile + the CI workflows | |
make dev-docs-verify | ✅ | regenerated command reference must match committed (CI red on drift) runs: dev-docs |
Documentation lint
| Target | CI | What it does |
|---|---|---|
make diagrams | format D2 sources and regenerate the committed SVG diagrams | |
make diagrams-verify | ✅ | regenerated D2 sources and SVG diagrams must match committed runs: diagrams |
make docs-lint | D2 + markdownlint + lychee (offline) + inline repo paths + Vale runs: diagrams-verify docs-lint-md docs-lint-links docs-lint-paths docs-lint-prose | |
make docs-lint-md | markdown structure (globs + rules live in .markdownlint-cli2.jsonc) | |
make docs-lint-links | relative-link check, offline, over the WIDE set (see lychee.toml for why) | |
make docs-lint-paths | inline-code repo paths in the live docs must exist (allowlist: scripts/check-doc-paths.allow) | |
make docs-lint-prose | repo vocabulary + proper-noun casing (.vale.ini — no stock style package) |
Frontend (Phase 13)
| Target | CI | What it does |
|---|---|---|
make fe-install | ✅ | install the web workspace (pnpm) |
make fe-tokens | regenerate the web theme stylesheet from the design-system tokens (CI diff must be empty) | |
make fe-tokens-verify | ✅ | regenerated token artifacts must match committed runs: fe-tokens |
make brand-assets | regenerate favicon, launcher, TV, and store artwork from the shared brand contract | |
make brand-assets-verify | verify every platform brand derivative matches the shared brand contract | |
make fe-codegen | ✅ | regenerate tokens + orval api client from api/openapi.yaml |
make fe-api-codegen | ✅ | regenerate only the orval api client from api/openapi.yaml |
make fe-lint | Biome lint + format check, import and boundary gates (web/; needs codegen first) | |
make knip | unused files, exports and dependencies in web/ (config: web/knip.ts) | |
make fe-lint-fix | Biome autofix — format + safe lint fixes (web/) | |
make fe | biome + codegen + knip + typecheck + unit tests + embedded SPA + storybook gallery runs: fe-checks fe-packages fe-unit | |
make fe-checks | ✅ | everything in fe except the tests: biome, knip, typecheck, SPA, storybook runs: fe-codegen |
make fe-packages | ✅ | unit tests of the packages the web app uses, after codegen runs: fe-codegen |
make fe-unit | ✅ | web unit tests after codegen (FE_SHARD=n/m runs one shard) runs: fe-codegen |
make clients | lint, test, typecheck, and bundle the shared browser, mobile, and TV scaffold runs: clients-checks clients-tests clients-bundles | |
make clients-checks | ✅ | everything in clients except the mobile and TV tests and bundles runs: brand-assets-verify knip |
make clients-tests | ✅ | typecheck and test the mobile and TV clients and the packages they use (CLIENTS_APP=mobile |
make clients-bundles | ✅ | bundle the mobile and TV clients for Android, iOS, and their TV platforms (CLIENTS_APP=mobile |
make client-android-debug | ✅ | memory-bounded arm64 debug build (CLIENT_APP=mobile |
make shield-sideload | build and inspect a signed permanent-identity Shield APK (SHIELD_VERSION=x.y.z) runs: fe-api-codegen | |
make shield-sideload-test | build with an ephemeral key, then clean-install and launch on the TV emulator runs: fe-api-codegen | |
make client-apple-simulator | ✅ | build and launch an Apple simulator proof (CLIENT_APP=mobile |
make storybook | Storybook dev workshop on this worktree’s isolated port | |
make storybook-build | offline storybook-static build (what fe-visual snapshots) | |
make ensure-playwright-image | use a cached Playwright image or pull it with bounded retries | |
make fe-visual | ✅ | Playwright visual + a11y over storybook-static, in the pinned Docker image (§5.2) runs: storybook-build ensure-playwright-image |
make fe-visual-update | ✅ | regenerate the committed Linux baselines in the Docker image (sanctioned update path) runs: storybook-build ensure-playwright-image |
make e2e | ✅ | wizard e2e smoke vs a mocked backend, in the pinned Docker image (13.3 gate) runs: fe-build ensure-playwright-image |
make tuner-e2e | 100-Channel tuner controller matrix in Chromium, Firefox, and WebKit (§9.1) runs: fe-build ensure-playwright-image | |
make tuner-quarantine | ✅ | resolve the tuner tests the flake quarantine holds out (TUNER_QUARANTINE=exclude |
make tuner-e2e-host | ✅ | 100-Channel tuner controller matrix in host-installed browsers (§9.1); TUNER_PROJECT / TUNER_REPEAT_EACH narrow a manual rerun runs: fe-build |
make tuner-e2e-quarantine | ✅ | only the tuner tests the flake quarantine holds out (after tuner-quarantine) runs: tuner-e2e-host |
make route-timing-e2e-host | ✅ | route timing budgets (warm and cold, main nav) in host-installed Chromium (#3399) runs: fe-build |
make e2e-update | ✅ | regenerate the committed e2e page snapshots (sanctioned update path) runs: fe-build ensure-playwright-image |
Maintainer smoke (NOT CI)
| Target | CI | What it does |
|---|---|---|
make smoke | maintainer smoke: drive the REAL stack (starts it only if it isn’t up) | |
make smoke-reset | force a true FIRST RUN (wipes the smoke database + Tunarr), then run | |
make smoke-livetv | Live TV wiring vs a DISPOSABLE Jellyfin (destroyed after — never touches your media server) | |
make smoke-down | tear down the smoke stack (container, volume, temp database) |
Android TV React Native release
| Target | CI | What it does |
|---|---|---|
make android | React Native Android TV — verified unsigned four-ABI Play artifact runs: android-release-test | |
make android-release-test | compile once, strip the ephemeral CI signature, and retain promotion evidence | |
make android-profile | ✅ | profile the unchanged Android gate with separate timing and memory evidence |
What CI runs
agent-harness-test · android-profile · arch-docs-verify · ci-lint · client-android-debug · client-apple-simulator · clients-bundles · clients-checks · clients-tests · compose-verify · config-docs-verify · db-docs-verify · dev-docs-verify · diagrams-verify · e2e-update · e2e · eval-contract · fe-api-codegen · fe-checks · fe-codegen · fe-install · fe-packages · fe-tokens-verify · fe-unit · fe-visual-update · fe-visual · fmt · go-cache-warm · go-race-verify · go-shard-verify · image-bench · image-cert · image-parallelism-bench · lint · observability-verify · openapi-verify · playout-bench · privacy-verify · release-verify · retired-verify · route-timing-e2e-host · rust-check · scan-scale · shellcheck · tags-verify · test-ffmpeg · test-pg · test · tuner-e2e-host · tuner-e2e-quarantine · tuner-quarantine · vet-tags · vet · vuln
These are the targets a workflow step invokes DIRECTLY. Their prerequisites run too —
for example, check-static expands to formatting, vet, lint, and repository
contracts. Read the runs: line in each table above for the full picture.
A target absent from both is yours to run deliberately: the maintainer smoke suites and the tagged builds are not gates and never run unattended.