just-automation-practices

name	just-automation-practices
description	Best practices for using just command runner and task automation in development workflows.

Just automation practices

Purpose

Guide for using the just command runner for task automation, covering recipe design, variable handling, and cross-platform development.

When to use

This skill activates when:

• Creating Justfiles
• Writing build/test automation
• Defining development workflows
• Setting up task dependencies
• Cross-platform automation

Core concepts

Basic recipe

# Run tests
test:
    uv run pytest

# Run with arguments
test-file file:
    uv run pytest {{file}}

# Default recipe (runs when just called without arguments)
default: lint test

Recipe with dependencies

# Dependencies run first
build: lint test
    uv run python -m build

# Clean before build
clean-build: clean build

Variables

Setting variables

# Simple variables
python := "uv run python"
pytest := "uv run pytest"

# Using variables
test:
    {{pytest}} tests/

# Environment variables
export PYTHONPATH := "src"

test:
    {{pytest}} tests/

Built-in functions

# Current directory
project_dir := justfile_directory()

# Parent directory
parent := parent_directory(justfile_directory())

# Environment with default
python := env_var_or_default("PYTHON", "python3")

Arguments and parameters

Positional arguments

# Required argument
test file:
    uv run pytest {{file}}

# Optional with default
test file="tests/":
    uv run pytest {{file}}

# Variadic (all remaining args)
test *args:
    uv run pytest {{args}}

Named parameters

# Named with defaults
build target="release" output="dist":
    echo "Building {{target}} to {{output}}"

Conditionals

# Conditional execution
test:
    #!/usr/bin/env bash
    if [[ -f "tests/integration" ]]; then
        uv run pytest tests/integration
    fi

# Using just's if
python := if os() == "windows" { "python" } else { "python3" }

Multi-line recipes

# With shebang
setup:
    #!/usr/bin/env bash
    set -euo pipefail

    echo "Setting up environment..."
    uv sync
    echo "Done!"

# Default shell recipes
install:
    uv sync
    echo "Dependencies installed"

Common patterns

Development workflow

# Install dependencies
install:
    uv sync

# Format code
format:
    uv run ruff format .

# Lint code
lint:
    uv run ruff check .
    uv run basedpyright

# Run tests
test *args:
    uv run pytest {{args}}

# Full check before commit
check: format lint test

# Clean artifacts
clean:
    rm -rf dist/ .pytest_cache/ .coverage htmlcov/

Parameterized builds

# Build with options
build target="release":
    #!/usr/bin/env bash
    case "{{target}}" in
        release)
            uv run python -m build
            ;;
        dev)
            uv pip install -e .
            ;;
        *)
            echo "Unknown target: {{target}}"
            exit 1
            ;;
    esac

Environment management

# Set environment for recipes
set dotenv-load := true

# Use .env file
test:
    uv run pytest

# Override environment
test-ci:
    CI=true uv run pytest

Cross-platform

OS detection

# Different commands per OS
open_browser := if os() == "macos" {
    "open"
} else if os() == "windows" {
    "start"
} else {
    "xdg-open"
}

docs:
    {{open_browser}} docs/_build/html/index.html

Path handling

# Cross-platform paths
project_dir := justfile_directory()
src_dir := project_dir / "src"
tests_dir := project_dir / "tests"

Organization

List recipes

# Show available recipes
just --list

# Show recipe with description
just --show test

Documentation

# Recipe descriptions appear in --list
# Run all tests with coverage
test:
    uv run pytest --cov

# Format code using ruff
format:
    uv run ruff format .

Grouping with aliases

# Main recipe
test-all:
    uv run pytest

# Aliases for convenience
alias t := test-all
alias tests := test-all

Checklist

• Default recipe defined
• Recipes have descriptions (comments)
• Variables used for repeated values
• Dependencies properly declared
• Cross-platform compatible (if needed)
• Error handling in complex recipes

---

Additional resources:

• just documentation