Command Reference¶

Every task in the project has one name, reachable four ways:


`dt <task>`	in any terminal — the primary spelling
`make <task>`	the same targets, if you prefer make
`<leader>p<key>`	in neovim
`nix run .#<task>`	for the tasks that must work without the development shell, which is what CI uses

dt is a dispatcher rather than a second implementation: it reads the task list from the Makefile's .PHONY lines, so it cannot offer a task that does not exist nor miss one that was just added. A mistyped task suggests the closest real names.

dt                      # this table, in the terminal
dt <group>              # one group, with descriptions
dt <task>               # run it
dt run --port 9090      # extra flags reach the underlying tool
dt check-data DATA_DIR=/srv/data   # NAME=value reaches make as a variable

When a name is both a task and a group

run, build, test, docs and release name both. The task wins, because dt test should run the tests — that is what anyone typing it means. dt help test is the unambiguous form for the group. Names that are only groups — develop, diagnose, flake, data — need no such ceremony.

This page is generated

The tables below are produced by calling scripts/shell-help.sh at build time — the same source that renders the greeting in nix develop, backs dt, and answers make help. Adding a command there makes it appear in all four places from one edit, which is the point: this page previously described the make targets long after dt had replaced them.

RUN¶

start the app

Command	What it does
`dt run`	Desktop app in its own window — builds whatever is stale
`dt serve`	Web server only; open http://localhost:8080 in a browser
`dt run --port 9090`	Extra arguments are passed through to the binary
`nix run`	Desktop app from a reproducible build
`nix run .#serve`	Web server from a reproducible build
`<leader>pr / ps`	The same two from inside neovim

DEVELOP¶

hot reload

Command	What it does
`dt dev-all`	Go hot-reload + Vite HMR — open http://localhost:5173
`dt dev-backend`	Go backend only, auto-rebuilding on :8080
`dt dev-frontend`	Vite dev server only, HMR on :5173

BUILD¶

make artefacts

Command	What it does
`dt app`	Frontend, docs and binary — everything needed to run
`dt build-frontend`	Frontend only, into the embed directory
`dt build-docs`	Documentation site only, into the embed directory
`dt clean`	Remove build artifacts
`nix build`	Full reproducible build to ./result
`dt container`	Deployment container image, built from the flake

TEST¶

prove it works

Command	What it does
`dt test`	Go tests with race detector and coverage
`dt test-frontend`	Frontend tests (vitest)
`dt test-scripts`	Tests for the shell scripts
`dt test-all`	All three suites
`nix flake check`	Every check, in a sandbox

MEASURE¶

is it faster?

Command	What it does
`dt benchmark`	Measure the server, compare against every prior run, open the PDF
`dt benchmark-quick`	The same without the load phase; seconds, not minutes
`dt benchmark-report`	Rebuild and open the report for a recorded run
`dt benchmark-list`	What has been measured so far
`dt benchmark-regressions`	Where in the history a measurement changed, and which commit

DIAGNOSE¶

what is wrong?

Command	What it does
`dt run --diag`	Report what the desktop window resolved its layout to
`dt doctor`	Is this checkout healthy? Reports; changes nothing
`dt protect-branch`	Require the CI checks before anything reaches main
`dt doctor-deep`	The same, plus recomputing the real nix hashes
`dt check-data`	Check ./data and summarise every file in it
`dt lint`	golangci-lint over the Go sources, per .golangci.yml
`dt fmt`	gofmt -s the Go sources in place
`dt fmt-check`	Is everything formatted? What CI asks first; one second
`dt vet`	go vet — the pre-commit stand-in for the full linter
`dt check-shell`	shellcheck over every shell script in the repository
`dt check-nix`	Is flake.nix nixpkgs-fmt formatted?
`dt check-secrets`	gitleaks over the whole history
`dt check-drift`	Has the data contract drifted from the code?
`dt check`	fmt-check, lint, shell, nix, secrets, test — CI's questions
`dt info`	Versions of the binary and the toolchain

FLAKE¶

stay importable

Command	What it does
`dt check-flake`	Is flake.nix in step with the manifests? Instant
`dt sync-flake`	Recompute the nix hashes after changing a dependency
`dt verify-flake`	Authoritative; recomputes the hashes for real
`dt hooks`	Install the git hooks that enforce this on commit
`dt vendor-fonts`	Refresh the committed typefaces from nixpkgs

DATA¶

the data pack

Command	What it does
`dt fetch-data FOLDER=..`	Download source CSVs from a Google Drive folder
`dt geopackage`	Build data/datapack.gpkg from the source CSVs
`dt pack-data`	Check the data, then build a distributable .zip
`dt pack-data --force`	Build the pack even when the check fails
`dt list-datapack`	Contents and checksum of the last pack built

DOCS¶

the doc site

Command	What it does
`dt docs`	Build the documentation site
`dt docs-serve`	Live-reloading preview on http://localhost:8000

RELEASE¶

ship it

Command	What it does
`dt packages`	Release packages for every platform buildable here
`dt packages-linux`	Linux .tar.gz, .deb, .rpm
`dt packages-windows`	Windows .zip and .msi
`dt release`	Full release build, with the tagging instructions

Where the commands live¶

Concern	Implementation
The list itself	`scripts/shell-help.sh`
Dispatch	`scripts/dt`, reading `.PHONY` from the `Makefile`
Launching the application	`scripts/run-app.sh` — every entry point, both modes
Deciding what to rebuild	`scripts/lib-build.sh`, shared by the launcher and the data tools
Terminal output	`scripts/lib-ui.sh`, shared by every reporting script
The shell environment	`scripts/dev-shell.sh`, sourced by the flake's `shellHook`

The nix run entry points are documented in Development Environment; they exist for the tasks CI needs to run without entering the development shell.