Skip to content

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

TargetCIWhat it does
make helpList targets

Agent / worktree harness

TargetCIWhat it does
make agent-startregister this worktree and its seams (TASK=… CLAIMS=a,b; optional DEPENDS_ON=task)
make agent-statuslist tool-neutral agent sessions across every worktree
make agent-renewrenew this worktree’s claim lease (AGENT_LEASE_HOURS=4)
make agent-pruneremove expired entries from the shared agent registry
make agent-stoprelease this worktree’s task and shared-output claims
make agent-envshow this worktree’s isolated ports, database, compose project, and artifact path
make agent-baselineshare one cached make verify SCOPE=all result per clean commit/toolchain
make agent-verifycompatibility alias for make verify
runs: verify
make test-affectedrun unit tests related to changed files during editing (not final evidence)
make agent-worktreecreate, claim, and bootstrap a sibling worktree (TOPIC=… CLAIMS=…; BASE/DEPENDS_ON for stacks)
make agent-gcaudit worktrees; APPLY=1 retires only exact clean merged PR heads
make agent-reaplist processes running in a worktree (WORKTREE=path, or ORPHANS=1 for deleted ones); APPLY=1 stops them
make dev-watchwatch local resources, your PRs and agent lanes; prints only when something needs attention
make bootstrapbuild the Rust worker and prepare frontend, isolated directories, and dev identity
make doctorverify 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-verifyverify 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-previewgenerate validated release notes (TAG required; optional PREVIOUS_TAG and OUTPUT)
make docs-release-gatefail a release whose user-facing changes have no docs change (TAG, PREVIOUS_TAG required; run after release-notes-preview, #1682)
make backup-restore-verifyisolated SQLite backup, destructive replacement, restore, and state validation
make backup-restore-drillSQLite + Docker-backed Postgres backup/restore drills
runs: backup-restore-verify
make graphbuild the local Graphify index in graphify-out/ (never committed; needs graphifyy, see docs/agents/graphify.md)

Proportional local verification

TargetCIWhat it does
make verifyrun affected local evidence; SCOPE=all runs the comprehensive repository audit

Explicit complete audit

TargetCIWhat it does
make check-staticrepository 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-workerbuild the debug Rust image worker required by Go unit tests
make rust-auditcheck Rust advisories, licences, and dependency sources (needs cargo-deny)
make rust-fuzzfuzz 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-vetgo 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 deadcodefunctions no ./cmd binary reaches, per package (report only; not a PR gate)
make deadcode-baselinerewrite 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-weightsregenerate 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-verifycompile 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 evalsemantic eval: real intents → real LLM → scored (needs LLM_*/LOOMARR_LIBRARY_DB/TMDB_API_KEY; NOT in the hermetic gate)
make eval-certcertify exact intents and mandatory scheduled viewer outcomes; fails closed and writes a scorecard
make eval-planner-certcompare one model against the frozen planner corpus; explicit, inference-spending, non-CI
make eval-planner-smokereplay one frozen base Intent per planner family; explicit, inference-spending, non-CI
make eval-query-expansion-diagnostic-dry-runpreflight the ten-case Gemini query diagnostic without inference
make eval-query-expansion-diagnosticrun the authorized ten-case Gemini query diagnostic (paid/manual)
make planner-tool-diagnosticprobe the exact post-catalog-result model turn; explicit, inference-spending, non-CI
make channel-recommend-certcertify inert channel concepts on the frozen recommendation corpus; explicit, inference-spending, non-CI
make channel-recommend-cert-dry-runemit the provider-free recommendation certification contract; no inference
make channel-recommend-diagnosticdiagnose recommendation JSON transport on the disjoint development corpus; explicit, inference-spending, non-CI
make channel-recommend-comparecompare channel-recommendation scorecards without inference
make eval-planner-comparecompare two or more frozen planner scorecards without inference
make planner-reference-hostbind one planner scorecard to exact local artifact and reference-host evidence; no inference
make eval-matrixexplicitly certify local + OpenRouter generation sequentially (manual, resource-heavy)
make filler-eval-contracthermetic filler-admission corpus and selective-risk contracts
make filler-temporal-truth-selectselect the private 48-case truth-review sample from frozen history without inference
make filler-temporal-truth-preparebuild the sealed complete-span 48-case evidence set without inference
make filler-temporal-assess-ollamaassess the sealed temporal challenge with a digest-pinned local model
make filler-temporal-comparecompare two independent temporal assessment sets without inference
make filler-temporal-selectderive an immutable stratified temporal calibration selection without inference
make filler-temporal-assess-openrouterrun a bounded paid temporal calibration on an exact snapshotted route
make filler-temporal-calibration-reportcompare one hosted temporal result with its two bound local assessments
make filler-corpus-commonsfreeze bounded Commons pilot and full-inventory artifacts
make filler-corpus-cdcfreeze bounded CDC pilot and full-inventory artifacts
make filler-corpus-locfreeze bounded LOC pilot and full-inventory artifacts
make filler-corpus-metfreeze a bounded metadata-only Met Museum inventory
make filler-corpus-met-rights-proposepre-screen frozen Met rights metadata without granting authority
make filler-corpus-met-rights-attestationprepare one pending, digest-bound Met rights attestation
make filler-corpus-met-rights-completeexpand one accepted Met attestation into item-bound review rows
make filler-corpus-nasafreeze bounded NASA pilot and full-inventory artifacts
make filler-corpus-pilotlock the qualified metadata-only filler rights-yield pilot
make filler-corpus-pilot-rights-reviewprepare the inert five-lane pilot review packet
make filler-corpus-pilot-rights-locklock completed pilot review into a non-authorizing yield report
make filler-corpus-archivefreeze a bounded rights-filtered Archive.org corpus inventory
make filler-corpus-inventorycombine strict source inventories for mixed-authority rights review
make filler-corpus-directfreeze an authored local cohort with rights and provenance evidence
make filler-corpus-preparebuild an unlabeled corpus draft and bounded evidence packets
make filler-corpus-downloaddownload only rights-approved corpus media under hard ceilings
make filler-visual-corpus-nomination-prepareprepare four-field visual nomination review from approved media
make filler-visual-corpus-nomination-locklock reviewed visual nominations into a private corpus source root
make filler-corpus-rights-reviewprepare an inert worksheet from a frozen filler inventory
make filler-corpus-rights-lockvalidate completed rights review CSV into approval JSONL
make filler-corpus-locklock two blind filler-label batches into a certification manifest
make filler-media-integrity-prepareprepare a label-free media-integrity challenge without inference
make filler-media-integrity-scorelock the private media-integrity comparison without inference
make filler-corpus-reviewprepare one opaque randomized filler-label review batch
make filler-corpus-review-packagematerialize one verified identity-blind reviewer evidence package
make filler-corpus-review-ollamacomplete one blind package with a digest-pinned local reviewer
make filler-corpus-review-openroutercomplete one blind package through a bounded pinned hosted reviewer
make filler-openrouter-snapshotlock OpenRouter capability, endpoint-price, and ZDR metadata
make filler-bakeoff-openroutercapture a bounded label-blind OpenRouter prediction ledger (paid/manual)
make filler-bakeoff-ollamacapture a digest-pinned local filler prediction ledger (manual)
make filler-bakeoff-transcribecapture digest-pinned shared filler transcripts (manual)
make filler-eval-certscore captured filler decisions; never contacts a model or media source
make filler-release-readinessproduce the beta filler release GO/HOLD report without network access
make filler-household-cohortbind the frozen beta filler seed to exact Ready playback outputs
make eval-planner-release-contractverify the frozen production-intent release corpus without inference
make eval-planner-release-gatereplay release-critical intents 10x with latency gates; explicit, inference-spending, non-CI
make eval-planner-model-canaryrun one bounded release-holdout trial for one configured planner model; explicit, inference-spending, non-CI
make eval-planner-model-finalistrepeat the model-canary cases 5x under an exact 1,000-call ceiling; explicit, inference-spending, non-CI

Build / run

TargetCIWhat it does
make buildbuild the cgo-free Go server and required Rust image worker
runs: rust-build
make rust-buildbuild 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-corpusgenerate 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-benchVMAF-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 devdev compose stack (external deps: tunarr-dev; portable Mac/Linux, CPU transcode)
make observability-devseed SQLite if needed, then start isolated local Prometheus + Grafana
make observability-dev-downstop this worktree’s local observability stack (preserves its data)
make observability-dev-testprove seeded Loomarr metrics and Grafana provisioning over real Docker + HTTP
make db-viewbrowse a copy of a database in CloudBeaver until Ctrl-C (FILE=backup.db, URL=postgres://…, ENGINE=postgres)
make test-ssoSSO against REAL Authelia + Authentik containers (requires Docker)
make dev-bebackend with live reload (Air) — rebuilds + restarts on Go/Rust changes
make rust-dev-buildbuild the debug Rust image worker the Go tests use (make dev-be runs a release one)
make dev-gpudev compose stack with NVIDIA transcode overlay (Linux + nvidia-container-toolkit)
make dev-fefrontend with HMR on this worktree’s isolated port, proxying its backend
make seedpopulate a dev store via the real domain paths (approval gate honored — AGENTS.md)
make demo-siterun the demo site from an image: VERSION=, or LOOMARR_IMAGE=
make demo-site-downstop the demo site and delete its data
make migration-rehearsalboot 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-gatehas COMMIT passed the playout bench on Intel and NVIDIA?
make demo-libraryserve the demo library’s Emby-compatible stand-in (generates its clips and art on first run)
make demo-titles-verifyno 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-seedpoint this worktree’s backend at the running demo library and create the demo channels (idempotent)
make docs-captureregenerate the docs screenshots from the demo seed (needs dev-be, dev-fe, demo-library, demo-seed)

Store conformance (Phase 3/4)

TargetCIWhat it does
make ensure-postgres-test-imageuse 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-lifecyclecertify Postgres conformance plus fresh-PG and SQLite→PG deployment lifecycles (Docker)
runs: test-pg

CI build-cache warming (#1570)

TargetCIWhat 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)

TargetCIWhat it does
make openapiexport 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)

TargetCIWhat it does
make config-docsgenerate docs/reference/settings.md from the settings registry
make settings-keysregenerate 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)

TargetCIWhat it does
make db-docsgenerate 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)

TargetCIWhat it does
make arch-docsregenerate 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)

TargetCIWhat it does
make dev-docsgenerate 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

TargetCIWhat it does
make diagramsformat D2 sources and regenerate the committed SVG diagrams
make diagrams-verify✅regenerated D2 sources and SVG diagrams must match committed
runs: diagrams
make docs-lintD2 + 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-mdmarkdown structure (globs + rules live in .markdownlint-cli2.jsonc)
make docs-lint-linksrelative-link check, offline, over the WIDE set (see lychee.toml for why)
make docs-lint-pathsinline-code repo paths in the live docs must exist (allowlist: scripts/check-doc-paths.allow)
make docs-lint-proserepo vocabulary + proper-noun casing (.vale.ini — no stock style package)

Frontend (Phase 13)

TargetCIWhat it does
make fe-install✅install the web workspace (pnpm)
make fe-tokensregenerate 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-assetsregenerate favicon, launcher, TV, and store artwork from the shared brand contract
make brand-assets-verifyverify 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-lintBiome lint + format check, import and boundary gates (web/; needs codegen first)
make knipunused files, exports and dependencies in web/ (config: web/knip.ts)
make fe-lint-fixBiome autofix — format + safe lint fixes (web/)
make febiome + 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 clientslint, 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-sideloadbuild and inspect a signed permanent-identity Shield APK (SHIELD_VERSION=x.y.z)
runs: fe-api-codegen
make shield-sideload-testbuild 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 storybookStorybook dev workshop on this worktree’s isolated port
make storybook-buildoffline storybook-static build (what fe-visual snapshots)
make ensure-playwright-imageuse 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-e2e100-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)

TargetCIWhat it does
make smokemaintainer smoke: drive the REAL stack (starts it only if it isn’t up)
make smoke-resetforce a true FIRST RUN (wipes the smoke database + Tunarr), then run
make smoke-livetvLive TV wiring vs a DISPOSABLE Jellyfin (destroyed after — never touches your media server)
make smoke-downtear down the smoke stack (container, volume, temp database)

Android TV React Native release

TargetCIWhat it does
make androidReact Native Android TV — verified unsigned four-ABI Play artifact
runs: android-release-test
make android-release-testcompile 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.