How to Use Just: A Beginner's Guide to the Just Command Runner

CodexFuse Team · 2026-11-02T01:50:52.618Z · 11 min read min read

What Is Just (the Command Runner), Exactly?

The Just command runner is a small, single-binary program that stores a project's shell commands as named recipes in a file called a justfile, and runs any of them with just recipe-name. One clarification first, said once: "just" is also an ordinary English word, so this guide is about the Just command runner (casey/just), the developer tool — not the adverb, and not the no-code automation platform Make.com, which is a different product in a different lane.

Casey, Just's author, draws the boundary himself: "just is a command runner, not a build system, so it avoids much of make's complexity and idiosyncrasies." In practice that means you type each project command once, document it with a comment, and everyone on the team runs the identical thing — no more "how do I run the tests again?" in chat. This guide teaches how to use Just end to end: install, first justfile, Just recipes with parameters, and the moment a makefile should become one.

If you manage containers, our Docker beginner guide pairs naturally with justfiles that wrap docker compose workflows, and since justfiles live inside repos, the Git beginner guide covers the version-control half of the setup. Together they turn a fresh clone into a one-command project.

How Do You Install Just?

You install Just with your system's package manager or the official install script — the manual lists no single preferred route, saying only "your favorite package manager." The current release is 1.59.0, published October 15, 2026, and every route below installs a current build.

Verify the install with one command:

just --version
# just 1.59.0

Two install notes worth knowing. The install script calls GitHub's API to find the latest release, and those calls are rate-limited per IP — on shared networks, pass a specific tag with --tag or set a GITHUB_TOKEN. On Windows, Just works with the sh bundled with Git for Windows, GitHub Desktop, or Cygwin; the manual warns that cmd.exe is fiddly, so PowerShell is the recommended shell for Windows users.

For CI, GitHub Actions runners already carry package managers — brew install just on macOS runners, choco install just on Windows runners — or use the community extractions/setup-just@v3 action. Our GitHub Actions beginner guide walks through workflow files if you are new to CI.

What Does Your First Justfile Look Like?

A justfile is a plain-text file named justfile (or .justfile) in your project root; each recipe is a name followed by a colon, with its shell commands indented underneath. Here is a complete first justfile:

# greet the team
hello:
  @echo "Hello from Just!"

# run the test suite, then the linter
check: test lint
  @echo "All checks passed."

test:
  ./run-tests.sh

lint:
  ./run-lint.sh

Three commands teach the whole model. Bare just runs the first recipe in the file (hello), just check runs the check recipe, and check: test lint declares dependencies — test and lint run before check's own body, and in a single invocation a recipe with the same arguments only ever runs once.

The @ prefix is the first surprise for shell-script migrants: Just prints each command to standard error before running it, narrating as it goes, and @ suppresses that echo for the line. That narration is why your terminal shows the command text above its output — it is Just talking, not your script. One more convenience the manual states plainly: Just can be invoked from any subdirectory, not just the directory containing the justfile, so nested project folders still reach the same recipes.

How Do Recipe Parameters Work?

Just recipe parameters work like function arguments — serve port="8080": gives port a default, and just serve 3000 overrides it on the command line. The README lists this as a headline feature: recipes can accept command line arguments, including flags and options.

# start the dev server (override the port: just serve 3000)
serve port="8080":
  @echo "Starting server on port {{port}}..."
  ./server --port {{port}}

Curly-brace interpolation — {{port}} — drops the parameter into the command, and the manual's canonical example shows defaults composing with extra arguments, like just test server unit filling two parameters at once. Defaults make recipes self-documenting: a teammate who runs just serve gets the sane port, and one who needs something else passes it without editing the file.

How Do You Keep Recipes Discoverable?

A # comment line directly above a recipe becomes its documentation in just --list, so the justfile documents itself — no wiki page to rot. The manual states it in one sentence: "Comments immediately preceding a recipe will appear in just --list."

# build the project
build:
  cargo build --release

# deploy to staging
deploy: build
  ./deploy.sh staging

Running just --list prints each recipe with its comment, which is the whole onboarding story: clone the repo, run just --list, pick a recipe. Two more introspection commands round it out — just --summary prints every recipe name on one line, and just --show deploy prints a recipe's source before you run something unfamiliar.

When the list grows long, just --choose opens a fuzzy finder to pick a recipe interactively instead of typing its name. One catch, said once: the default chooser is fzf, which must be installed (or point $JUST_CHOOSER at your own), and recipes that require arguments are excluded from the chooser since there is nowhere to type them.

How Do Justfiles Grow With a Project?

Big justfiles stay manageable three ways: justfile modules with mod, shared snippets with import, and the Just dotenv pattern — set dotenv-load reading secrets from a .env file. Modules, stabilized in Just 1.31.0, are the main growth mechanism: mod test loads test.just from the same directory, and its recipes run as just test unit or just test::unit. A custom path works too, as mod docs "path/to/docs.just".

set dotenv-load

# deploy with credentials from .env (never commit .env)
deploy:
  @echo "Deploying with database $DATABASE_ADDRESS..."
  ./deploy.sh --database $DATABASE_ADDRESS

With dotenv-load set, Just loads a .env file if one is present, and the README calls this out as a headline feature: it makes populating environment variables easy. Two companion settings are worth one line each: set export exports all Just variables as environment variables, and set allow-duplicate-recipes lets a later recipe with the same name override an earlier one (off by default, so accidental redefinition is an error, not a silent surprise).

Recipes are not limited to shell. A recipe whose body starts with #! is a shebang recipe — Just saves the body to a file and executes it — so the same justfile can host Python or Node.js recipes, exactly as the manual demonstrates:

report:
  #!/usr/bin/env python3
  print("Hello from python!")

Conditionals stay small and expression-shaped: env := if "prod" == target { "live" } else { "staging" } assigns a variable, and {{ if debug == "1" { "--verbose" } else { "" } }} interpolates inside a recipe. They short-circuit, evaluating only the branch they take.

When Does Just Beat a Makefile?

Just beats Makefiles the moment your makefile is only a list of phony task targets — Just treats every recipe as phony, passes arguments like a real CLI, and behaves the same on Linux, macOS, and Windows. The comparison the manual makes is explicit, and this original table compresses the just vs make decision:

The graduation rule of thumb: if your makefile tracks file dependencies and rebuilds artifacts, keep Make — that is what it is for. If it is a graveyard of .PHONY targets running linters, servers, and deploy scripts, that makefile wants to be a justfile. Sibling command runners exist — Task (YAML-based), Mage (Go-based), and Mask (Markdown-based) solve the same itch with different syntax — but they are comparison members of this lane, not rival pages; this guide covers Just, the lane's most widely adopted option.

Longevity is part of the pitch, and the manual makes an unusually blunt promise: "With the release of version 1.0, just features a strong commitment to backwards compatibility and stability... There will never be a just 2.0." A justfile you write today runs on every future 1.x release.

What Mistakes Do Just Beginners Make?

Every mistake below comes from a documented Just behavior, not folklore — this original table pairs each with the rule it violates:

Your first thirty minutes with Just, as a numbered arc: install it with your package manager, run just --version to confirm 1.59.0, write the two-recipe justfile from the section above, add one parameterized recipe, then run just --list and watch your project's commands document themselves. Pair the habit with our Pre-commit beginner guide so the recipes your team runs are the same ones your hooks enforce.

Sources

1. Just manual (print edition) — just.systems/man/en/print.html — install routes, recipe syntax, settings, and the "command runner, not a build system" line (fetched 2026-11-02).
2. casey/just releases API — api.github.com/repos/casey/just/releases/latest — 1.59.0 published 2026-10-15 (fetched 2026-11-02).
3. casey/just CHANGELOG — raw.githubusercontent.com/casey/just/master/CHANGELOG.md — 1.59.0 dated 2026-10-14; 1.58.0 and 1.56.0 notes (fetched 2026-11-02).
4. casey/just README — the backwards-compatibility promise and feature differentiators (fetched 2026-11-02).
5. LWN — lwn.net/Articles/1047715/ — news explainer on Just's recipe model and history (fetched 2026-11-02).
6. hledger manual — hledger.org/just.html — justfile recipes in a real finance workflow (fetched 2026-11-02).
7. "Learning just: A Practical Task Runner" — dev.to, September 2026 — the freshest independent walkthrough found (fetched 2026-11-02).
8. "Just: Harness Command Line Spells" — dev.to/danescher98 (2023) — personal justfile spell-book (fetched 2026-11-02).
9. "Just, start using it!" — berkkaraal.com, December 2024 — beginner introduction (fetched 2026-11-02).
10. "just: the task runner that should replace your Makefile" — amireslampanah.com — the make-switcher angle (fetched 2026-11-02).
11. x-cmd.com just install page — install-command reference (fetched 2026-11-02).
12. Ubuntu manpages — manpages.ubuntu.com, just(1) plucky — CLI reference (fetched 2026-11-02).
13. mastertheboss.com and cloudrumble.net — independent justfile tutorials (fetched 2026-11-02).

Frequently Asked Questions

Is Just a replacement for Make?

Just replaces Makefiles that are really just lists of phony task targets — linters, servers, deploys. It does not replace Make's build-system job: Just performs no dependency tracking and never skips an "up to date" recipe, because it is a command runner, not a build system. If your makefile rebuilds artifacts from file dependencies, keep Make.

Does Just work on Windows?

Yes — Linux, macOS, Windows, and other reasonable unixes are supported with no additional dependencies. Install with winget install --id Casey.Just --exact, Scoop, or Chocolatey, and use PowerShell rather than cmd.exe, which the manual calls fiddly. On Windows, Just runs recipes with the sh provided by Git for Windows, GitHub Desktop, or Cygwin.

How is Just different from npm scripts or Task?

npm scripts live inside package.json and belong to the JavaScript lane; Task is a sibling command runner that defines tasks in YAML. Just is language-agnostic with a make-like syntax, keeps its recipes in a dedicated justfile any project can adopt, and documents them through just --list without extra tooling.

Can I use Just with Docker Compose?

Absolutely — wrapping docker compose up, docker compose down, and rebuild commands in recipes is one of the most common justfile patterns, and dependencies let a deploy recipe run build first. See our Docker beginner guide for the compose side of the pairing.

Is Just stable, or will a 2.0 break my justfiles?

The project promises strong backwards compatibility and stability from version 1.0 onward, stating plainly that there will never be a Just 2.0. A justfile written against 1.59.0 keeps working on every future 1.x release.