/just-cli

name: just-cli
description: Documentation for just and justfile. This skill should be used before editing justfile or running just commands. TRIGGER when run just command, or edit justfile; or when about to write any `just ...` shell invocation in Bash, pueue, or scripts.

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.

**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)
set dotenv-load                   # Auto-load .env file
set positional-arguments          # Pass recipe args as $1, $2, etc.

Common Attributes

| Attribute | Purpose | | ------------------------- | ---------------------------------------------- | | `[arg("p", long, ...)]` | Configure parameter as `--flag` option (v1.46) | | `[group("name")]` | Group recipes in `just --list` output | | `[no-cd]` | Don't change to justfile directory | | `[private]` | Hide from `just --list` (same as `_` prefix) | | `[script]` | Execute recipe as single script block | | `[script("interpreter")]` | Use specific interpreter (bash, python, etc.) | | `[confirm("prompt")]` | Require user confirmation before running | | `[doc("text")]` | Override recipe documentation | | `[positional-arguments]` | Enable positional args for this recipe only |

Recipe Argument Flags (v1.46.0+)

The `[arg()]` attribute configures parameters as CLI-style options:

# Long option (--target)
[arg("target", long)]
build target:
    cargo build --target {{ target }}

# Short option (-v)
[arg("verbose", short="v")]
run verbose="false":
    echo "Verbose: {{ verbose }}"

# Combined long + short
[arg("output", long, short="o")]
compile output:
    gcc main.c -o {{ output }}

# Flag without value (presence sets to "true")
[arg("release", long, value="true")]
build release="false":
    cargo build {{ if release == "true" { "--release" } else { "" } }}

# Help string (shown in `just --usage`)
[arg("target", long, help="Build target architecture")]
build target:
    cargo build --target {{ target }}

**Usage examples:**

just build --target x86_64
just build --target=x86_64
just compile -o main
just build --release
just --usage build    # Show recipe argument help

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):

| Constant | Description | | -------------------------------------------------- | ------------------------------------------ | | `CYAN`, `GREEN`, `RED`, `YELLOW`, `BLUE`, `PURPLE` | Text colors | | `BOLD`, `ITALIC`, `UNDERLINE`, `STRIKETHROUGH` | Text styles | | `NORMAL` | Reset formatting | | `BG_*` | Background colors (BG_RED, BG_GREEN, etc.) | | `HEX`, `HEXLOWER` | Hexadecimal digits |

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

| Recipe | Alias | Recipe | Alias | | -------------- | ----- | -------------- | ----- | | full-check | fc | full-write | fw | | biome-check | bc | biome-write | bw | | prettier-check | pc | prettier-write | pw | | mdformat-check | mc | mdformat-write | mw | | tsc-check | tc