julianobarbosa/justfile

Just Command Runner 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, more portable, and avoids make's idiosyncrasies like .PHONY, tab sensitivity issues, and implicit rules.

When to Use Just vs Make

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

Core Concepts

Recipe = Target

Recipes are the core unit. Each recipe is a named set of commands:

recipe-name:
    command1
    command2

• Indentation MUST be consistent (spaces or tabs, but pick one — set ignore-comments helps)
• Each line runs in a separate shell by default (use set shell or shebang recipes for multi-line scripts)
• No .PHONY needed — just doesn't track file timestamps

Variables

# Assignment
version := "1.0.0"

# Backtick evaluation (runs command, captures stdout)
git_hash := `git rev-parse --short HEAD`

# Environment variable access
home := env('HOME')

# Export to recipe commands
export DATABASE_URL := "postgres://localhost/mydb"

Settings Block

Place settings at the top of the justfile:

set dotenv-load           # Load .env file
set positional-arguments  # Pass recipe args as $1, $2, etc.
set shell := ["bash", "-euco", "pipefail"]  # Fail-fast shell
set export                # Export all variables as env vars
set quiet                 # Suppress command echoing (like @ in make)

Recipe Arguments

# Required argument
deploy target:
    echo "Deploying to {{target}}"

# Default value
greet name="World":
    echo "Hello {{name}}"

# Variadic (one or more)
test +targets:
    go test {{targets}}

# Variadic (zero or more)
lint *flags:
    eslint {{flags}} src/

Dependencies

# Run 'build' before 'test'
test: build
    cargo test

# Pass arguments to dependencies
push: (deploy "production")

# Multiple dependencies
all: clean build test lint

Conditional Logic

# Ternary-style conditional
rust_target := if os() == "macos" { "aarch64-apple-darwin" } else { "x86_64-unknown-linux-gnu" }

# In recipes
check:
    if [ -f .env ]; then echo "Found .env"; fi

Platform-Specific Recipes

[linux]
install:
    sudo apt install ripgrep

[macos]
install:
    brew install ripgrep

[windows]
install:
    choco install ripgrep

Recipe Attributes

[private]           # Hidden from --list
[no-cd]             # Don't cd to justfile directory
[confirm]           # Ask confirmation before running
[confirm("Deploy to production?")]
[no-exit-message]   # Suppress error message on failure
[group("deploy")]   # Group in --list output
[doc("Run the full test suite")]  # Custom doc string

Shebang Recipes (Multi-line Scripts)

When a recipe needs to run as a single script rather than line-by-line:

process-data:
    #!/usr/bin/env python3
    import json
    with open("data.json") as f:
        data = json.load(f)
    print(f"Found {len(data)} records")

Self-Documenting Help

# The default recipe — runs when you type `just` with no args
[private]
default:
    @just --list --unsorted

Comments above recipes become descriptions in just --list:

# Initialize Terraform with backend config
init:
    terraform init

Imports and Modules

# Import another justfile
import 'ci.just'

# Module (namespaced)
mod deploy 'deploy.just'
# Usage: just deploy::production

References

• references/justfile-patterns.md — Common justfile patterns by project type
• references/make-migration.md — Makefile-to-justfile migration guide

Useful Functions

| Function | Purpose | | ------------------------- | -------------------------------------------- | | os() | Current OS (linux, macos, windows) | | arch() | CPU architecture (x86_64, aarch64) | | env('KEY') | Get environment variable (aborts if missing) | | env('KEY', 'default') | Get env var with fallback | | invocation_directory() | Directory where just was called from | | justfile_directory() | Directory containing the justfile | | join(a, b) | Join path components | | parent_directory(path) | Parent of path | | file_name(path) | Filename component | | without_extension(path) | Remove file extension | | uppercase(s) | Uppercase string | | lowercase(s) | Lowercase string | | replace(s, from, to) | String replacement | | trim(s) | Trim whitespace | | quote(s) | Shell-quote a string | | sha256_file(path) | SHA-256 hash of file | | shell(cmd, args...) | Execute command, capture output |

Installation

# macOS
brew install just

# Cargo
cargo install just

# Pre-built binaries
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

# Shell completions
just --completions zsh > ~/.zsh/completions/_just
just --completions bash > /etc/bash_completion.d/just

---

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 or set shell 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, not the local one. 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 to inside the recipe if not needed globally.
• Recipe arguments don't shell-quote automatically: just deploy "my server" passes two args, not one. Use set positional-arguments and "$@", or wrap in {{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 recipes starting with _ or marked [private] but they're still callable — security through obscurity, not actual access control.
• Cross-platform [macos]/[linux] attributes silently skip the recipe on other OSes — running just install on Windows when only [linux] and [macos] variants exist exits 0 with no error, which looks like success.