Just Command Runner

Overview

Expert guidance for Just, a command runner with syntax inspired by make. Use this skill for creating justfiles, writing recipes, configuring settings, and implementing task automation workflows.

Justfile Discovery Protocol

When a justfile exists in a project, agents should prefer just recipes over raw commands.

Discovery Steps

1. Check for justfile or Justfile in project root
2. Run just --list to discover available recipes
3. Map common operations to recipes:

Common Recipe Naming Conventions

• test / t - Run test suite
• build / b - Build project
• lint - Run linter
• fmt - Format code
• check - Type checking / static analysis
• coverage - Generate coverage report
• audit - Security audit
• dev / serve - Start development server
• clean - Remove build artifacts
• full-check / fc - Run all checks

Key capabilities:

• Create and organize justfiles with proper structure
• Write recipes with attributes, dependencies, and parameters
• Configure settings for shell, modules, and imports
• Use built-in constants for terminal formatting
• Implement check/write patterns for code quality tools

Quick Reference

Essential Settings

set allow-duplicate-recipes       # Allow recipes to override imported ones
set allow-duplicate-variables     # Allow variables to override imported ones
set shell := ["bash", "-euo", "pipefail", "-c"]  # Strict bash with error handling
set unstable                      # Enable unstable features (modules, script attribute)

Environment Variables: Use mise for environment variable management instead of Just's dotenv settings. mise provides project-scoped env vars via .mise.toml with better tooling integration.

Common Attributes

Multiple attributes can be combined:

[no-cd, private]
[group("checks")]
recipe:
    echo "hello"

Built-in Constants

Terminal formatting constants are globally available (no definition needed):

Usage:

@status:
    echo -e '{{ GREEN }}Success!{{ NORMAL }}'
    echo -e '{{ BOLD + CYAN }}Building...{{ NORMAL }}'

Key Functions

# Require executable exists (fails recipe if not found)
jq := require("jq")

# Get environment variable with default
log_level := env("LOG_LEVEL", "info")

# Get justfile directory path
root := justfile_dir()

Recipe Patterns

Status Reporter Pattern

Display formatted status during multi-step workflows:

@_run-with-status recipe *args:
    echo ""
    echo -e '{{ CYAN }}→ Running {{ recipe }}...{{ NORMAL }}'
    just {{ recipe }} {{ args }}
    echo -e '{{ GREEN }}✓ {{ recipe }} completed{{ NORMAL }}'
alias rws := _run-with-status

Check/Write Pattern

Pair check (verify) and write (fix) recipes for code quality tools:

[group("checks")]
@biome-check +globs=".":
    na biome check {{ globs }}
alias bc := biome-check

[group("checks")]
@biome-write +globs=".":
    na biome check --write {{ globs }}
alias bw := biome-write

Full Check/Write Pattern

Aggregate all checks with status reporting:

[group("checks")]
@full-check:
    just _run-with-status biome-check
    just _run-with-status prettier-check
    just _run-with-status tsc-check
    echo ""
    echo -e '{{ GREEN }}All code checks passed!{{ NORMAL }}'
alias fc := full-check

[group("checks")]
@full-write:
    just _run-with-status biome-write
    just _run-with-status prettier-write
    echo ""
    echo -e '{{ GREEN }}All code fixes applied!{{ NORMAL }}'
alias fw := full-write

Standard Alias Conventions

Modules & Imports

Import Pattern

Include recipes from another file:

import "./just/settings.just"
import "./just/base.just"
import? "./local.just"    # Optional (no error if missing)

Module Pattern

Load submodule (requires set unstable):

mod foo                   # Loads foo.just or foo/justfile
mod bar "path/to/bar"     # Custom path
mod? optional             # Optional module

# Call module recipes
just foo::build

Devkit Import Pattern

For projects using @sablier/devkit:

import "./node_modules/@sablier/devkit/just/base.just"
import "./node_modules/@sablier/devkit/just/npm.just"

Section Organization

Standard section header format:

# ---------------------------------------------------------------------------- #
#                                 DEPENDENCIES                                 #
# ---------------------------------------------------------------------------- #

Common sections (in order):

1. DEPENDENCIES - Required tools with URLs
2. CONSTANTS - Glob patterns, environment vars
3. RECIPES / COMMANDS - Main entry points
4. CHECKS - Code quality recipes
5. UTILITIES / INTERNAL HELPERS - Private helpers

Default Recipe

Always define a default recipe:

# Show available commands
default:
    @just --list

Dependencies Declaration

Document required tools at the top:

# ---------------------------------------------------------------------------- #
#                                 DEPENDENCIES                                 #
# ---------------------------------------------------------------------------- #

# Bun: https://bun.sh
bun := require("bun")

# Ni: https://github.com/antfu-collective/ni
na := require("na")
ni := require("ni")
nlx := require("nlx")

Additional Resources

Reference Files

For detailed patterns and comprehensive coverage, consult:

• [reference.md](references/reference.md) - Complete settings, modules, attributes, functions reference
• [patterns.md](references/patterns.md) - Established conventions, section organization, helper patterns

External Documentation

• Official Manual: https://just.systems/man/en/
• GitHub Repository: https://github.com/casey/just

Important Limitations

Just does not support flags. Recipe parameters are positional only:

# WRONG: Flags don't work
build --release:  # This won't work!

# CORRECT: Use positional parameters
build mode="debug":
    cargo build {{ if mode == "release" { "--release" } else { "" } }}

# Usage: just build release

For complex flag-like behavior, use environment variables or positional parameters with defaults.

Tips

1. Use @ prefix to suppress command echo: @echo "quiet"
2. Use + for variadic parameters: test +args
3. Use for optional variadic: build flags
4. Quote glob patterns in variables: GLOBS := "\"**/*.json\""
5. Use [no-cd] in monorepos to stay in current directory
6. Private recipes start with _ or use [private]
7. Always define aliases after recipe names for discoverability