Justfile

Justfile Skill

just is a command runner (not a build system) that saves and runs project-specific commands in a file called Justfile. It uses make-inspired syntax but is simpler and more portable, with none of make's idiosyncrasies (.PHONY, tab sensitivity, implicit rules, timestamp tracking).

This skill enforces a consistent house style so every Justfile looks the same across projects. The rules below are the authoritative convention; Tools/lint.ts validates the deterministic ones.

Workflow Routing

Trigger	Workflow
"create a justfile", "set up just", "add a recipe/module"	Workflows/CreateJustfile.md
"migrate Makefile to just", "convert make to just"	Workflows/MigrateFromMake.md
"check/lint this justfile", "is this justfile correct"	Workflows/CheckJustfile.md

When to Use Just vs Make

Scenario	Tool
Project task automation (build, test, deploy, lint)	just
Cross-platform command runner	just
Actual file-based build dependencies (compile .c → .o)	make
Legacy projects already deep in make	make (or migrate)

Common Mistakes — do NOT do these

Patterns the model often generates incorrectly. Check output against this list.

WRONG	RIGHT
justfile (lowercase)	Justfile (capital J)
mod docker (bare)	mod docker '.justfiles/docker.just'
Module at docker.just or just/docker.just	Module at .justfiles/docker.just
default:	_default: (underscore required)
@just --list	@just --list --unsorted (module) or --unsorted --list-submodules (root with modules)
env("NAME", "val")	env_var_or_default("NAME", "val")
Module file without the three-line header	Every file gets the full header
Module file without its own _default recipe	Every file gets its own _default
Module named after a tool (psql.just)	Module named after a concern (db.just)
Tests in docker.just because they run in a container	Tests in test.just — classify by purpose, not implementation
Root recipe duplicates module logic	Root shortcut delegates: build: docker-build
Ad-hoc names (run-tests, do-lint)	Standard names: test, lint, build, dev, fmt, check
Relative paths in module recipes (bash tests/run.sh)	Use source_directory() for absolute paths

Mandatory Rules — apply to EVERY file you create or edit

1. The root file MUST be named Justfile (capital J).
2. EVERY file (root and every .just module) MUST start with this three-line header:

   #!/usr/bin/env just --justfile
   set shell := ["bash", "-euo", "pipefail", "-c"]
   set dotenv-load := true
   

   Use set dotenv-load := false where appropriate, but the line must always be present.
3. EVERY file MUST have _default as its first recipe:

   # List all available recipes
   _default:
       @just --list --unsorted
   

   The root Justfile with modules uses @just --list --unsorted --list-submodules. Module files use @just --list --unsorted (no --list-submodules).
4. Section order in every file: variables → mod imports → recipes.
5. Module files MUST live at .justfiles/<name>.just — never just/, never beside the root.
6. Import modules with explicit paths: mod name '.justfiles/name.just' — never bare mod name.
7. Use env_var_or_default("NAME", "value") for variable defaults — never env().
8. Every recipe gets a # doc comment on the line directly above it.
9. Parameterized recipes document each param: # param - description (default: value).
10. Private/helper recipes start with _.
11. Dependencies go on the definition line: build: _lint test.
12. Destructive recipes prompt for confirmation; the doc comment says "DESTRUCTIVE, prompts for confirmation".
13. Extract modules by domain concern, named after the concern (db.just) not the tool (psql.just). The root Justfile is a thin orchestrator: _default, shortcut recipes, and project-wide recipes like check/clean.
14. The root provides shortcut recipes for common workflows that delegate to modules, giving developers a flat namespace for everyday tasks.
15. Use the standard recipe vocabulary below as the public API. Never invent run-tests, do-lint, compile, format.
16. In modules, never use bare relative paths — module recipes run with the module's directory as CWD. Define root := source_directory() / ".." and reference files as {{root}}/tests/run.sh.

Standard Recipe Vocabulary

A developer should be able to run just test, just dev, or just check in any project without guessing. Use these exact names; include only the ones that apply.

Recipe	Purpose	Include when
dev	Start dev environment (server, watch, REPL)	Project has a dev loop
test	Run the test suite	Always
build	Build or compile	Project has a build step
lint	Run linters	Linters configured
fmt	Format code	Formatters configured
check	Run ALL quality gates (check: lint test)	Always
clean	Remove build artifacts, caches, generated files	Project produces output

check is the meta-recipe — depend on the applicable gates and add format checks (cargo fmt --check, ruff format --check) as appropriate.

Namespacing by Concern

Group by domain, not tool. Classify by purpose: a test that runs in Docker is a testing recipe (test.just), not a Docker recipe. A migration that uses kubectl is a database recipe (db.just).

Concern	Module	Typical recipes
Development	dev.just	build, test, lint, fmt, bench
Testing	test.just	run, list, watch, coverage
Containers	docker.just	build, push, run, compose-up
CI/CD	ci.just	lint, deploy, release
Database	db.just	migrate, seed, reset, dump, restore
Infrastructure	infra.just	plan, apply, destroy
Kubernetes	k8s.just	apply, diff, rollback, logs
Documentation	docs.just	build, serve, publish

Single-concern projects (e.g. a Go/Rust project with only build/test/lint/fmt) use one dev.just; the root still stays thin. Modules are self-contained: own variables, own _default, no cross-module recipe dependencies.

Templates & References

• Templates (root + module, copy-and-adapt): Templates.md
• just language reference (variables, args, deps, conditionals, attributes, functions, install): References/Syntax.md
• Recipe fragments by project type (Terraform, Go, Python, Docker, Azure, Ansible): References/Patterns.md
• Makefile → just migration guide: References/MakeMigration.md

Linting

After creating or editing ANY Justfile or .just module, run the structural lint and fix every failure:

bun Tools/lint.ts <project-dir>

It checks file naming, the three-line header, _default as first recipe, the --unsorted/--list-submodules flags, env_var_or_default() usage, doc comments on all recipes, explicit module import paths, and section order. Any FAIL is a bug — fix and re-run until clean. The lint cannot judge concern-based naming, self-containment, or standard-vocabulary use — verify those by inspection (see Workflows/CheckJustfile.md).

Gotchas

• Each recipe line runs in a separate shell by default — cd foo on one line and ls on the next runs ls in the original directory. Use a shebang recipe for multi-line scripts.
• set dotenv-load loads .env from the justfile directory, not the invocation directory — running just from a subdirectory loads the parent's .env. Use set dotenv-path to override.
• Backtick variables evaluate at parse time, every invocation — git_hash := \git rev-parse HEAD`runs git on everyjust` call, even for unrelated recipes. Slow on large repos; move inside the recipe if not needed globally.
• Recipe arguments don't shell-quote automatically — just deploy "my server" passes two args. Use set positional-arguments with "$@", or wrap as {{quote(target)}}.
• set shell := ["bash", "-c"] breaks set -euo pipefail semantics because each line is its own -c invocation — pipefail only applies within that line. Use shebang recipes for proper fail-fast scripts.
• just --list hides _-prefixed and [private] recipes but they're still callable — obscurity, not access control.
• Cross-platform [macos]/[linux] attributes silently skip the recipe on other OSes — running just install on Windows when only [linux]/[macos] variants exist exits 0 with no error, which looks like success.
• The lint validates structure, not behavior — a recipe can pass every check and still run the wrong command. Run just --dry-run <recipe> to verify expansion.