Justfile Expert

Expert knowledge for Just command runner, recipe development, and task automation with focus on cross-platform compatibility and project standardization.

Core Expertise

Command Runner Mastery

• Justfile syntax and recipe structure
• Cross-platform task automation (Linux, macOS, Windows)
• Parameter handling and argument forwarding
• Module organization for large projects

Recipe Development Excellence

• Recipe patterns for common operations
• Dependency management between recipes
• Shebang recipes for complex logic
• Environment variable integration

Project Standardization

• Standard recipes for consistent workflows
• Self-documenting project operations
• Portable patterns across projects
• Integration with CI/CD pipelines

Key Capabilities

Recipe Parameters

• Required parameters: recipe param: - must be provided
• Default values: recipe param="default": - optional with fallback
• Variadic +: recipe +FILES: - one or more arguments
• Variadic *: recipe *FLAGS: - zero or more arguments
• Environment export: recipe $VAR: - parameter as env var

Settings Configuration

• set dotenv-load: Load .env file automatically
• set positional-arguments: Enable $1, $2 syntax
• set export: Export all variables as env vars
• set shell: Custom shell interpreter
• set quiet: Suppress command echoing

Recipe Attributes

• [private]: Hide from --list output
• [no-cd]: Don't change directory
• [no-exit-message]: Suppress exit messages
• [unix] / [windows]: Platform-specific recipes
• [positional-arguments]: Per-recipe positional args

Module System

• mod name: Declare submodule
• mod name 'path': Custom module path
• Invocation: just module::recipe or just module recipe

Essential Syntax

Basic Recipe Structure

# Comment describes the recipe
recipe-name:
    command1
    command2

Recipe with Parameters

build target:
    @echo "Building {{target}}..."
    cd {{target}} && make

test *args:
    uv run pytest {{args}}

Recipe Dependencies

default: build test

build: _setup
    cargo build --release

_setup:
    @echo "Setting up..."

Variables and Interpolation

version := "1.0.0"
project := env('PROJECT_NAME', 'default')

info:
    @echo "Project: {{project}} v{{version}}"

Conditional Recipes

[unix]
open:
    xdg-open http://localhost:8080

[windows]
open:
    start http://localhost:8080

Standard Recipes

Every project should provide these standard recipes:

# Justfile - Project task runner
# Run `just` or `just help` to see available recipes

set dotenv-load
set positional-arguments

# Default recipe - show help
default:
    @just --list

# Show available recipes with descriptions
help:
    @just --list --unsorted

####################
# Development
####################

# Run linters
lint:
    # Language-specific lint command

# Format code
format:
    # Language-specific format command

# Run tests
test *args:
    # Language-specific test command {{args}}

# Development mode with watch
dev:
    # Start with file watching

####################
# Build & Deploy
####################

# Build project
build:
    # Build command

# Clean build artifacts
clean:
    # Cleanup command

# Start service
start:
    # Start command

# Stop service
stop:
    # Stop command

Common Patterns

Setup/Bootstrap Recipe

# Initial project setup
setup:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "Installing dependencies..."
    uv sync
    echo "Setting up pre-commit..."
    pre-commit install
    echo "Done!"

Docker Integration

# Build container image
docker-build tag="latest":
    docker build -t {{project}}:{{tag}} .

# Run container
docker-run tag="latest" *args:
    docker run --rm -it {{project}}:{{tag}} {{args}}

# Push to registry
docker-push tag="latest":
    docker push {{registry}}/{{project}}:{{tag}}

Database Operations

# Run database migrations
db-migrate:
    uv run alembic upgrade head

# Create new migration
db-revision message:
    uv run alembic revision --autogenerate -m "{{message}}"

# Reset database
db-reset:
    uv run alembic downgrade base
    uv run alembic upgrade head

CI/CD Recipes

# Full CI check (lint + test + build)
ci: lint test build
    @echo "CI passed!"

# Release workflow
release version:
    git tag -a "v{{version}}" -m "Release {{version}}"
    git push origin "v{{version}}"

Best Practices

Recipe Development Workflow

1. Name clearly: Use descriptive, verb-based names (build, test, deploy)
2. Document always: Add comment before each recipe
3. Use defaults: Provide sensible default parameter values
4. Group logically: Organize with section comments
5. Hide internals: Mark helper recipes as [private]
6. Test portability: Verify on all target platforms

Critical Guidelines

• Always provide default recipe pointing to help
• Use @ prefix to suppress command echo when appropriate
• Use shebang recipes for multi-line logic
• Prefer set dotenv-load for configuration
• Use modules for large projects (>20 recipes)
• Include variadic *args for passthrough flexibility
• Quote all variables in shell commands

Comparison with Alternatives

When to use Just:

• Cross-project standard recipes
• Simple, readable task automation
• No tool version management needed

When to use mise tasks:

• Project-specific with tool version pinning
• Already using mise for tool management

When to use Make:

• Legacy projects with existing Makefiles
• Build systems requiring incremental compilation

For detailed syntax reference, advanced patterns, and troubleshooting, see REFERENCE.md.