---

name: just description: Bootstrap repos with just command runner. Use when setting up new projects, creating justfiles, or adding task automation. Provides ./dev bootstrap script that installs just, modular justfile structure in just/ directory, and recipe conventions.

Just Command Runner

Task automation using just with a standardized project structure.

Project Structure

Copyproject/
├── dev                 # Bootstrap script (installs just, runs `just dev`)
├── justfile            # Root: settings, imports, and modules
└── just/
    ├── dev.just        # Development recipes (imported, no namespace)
    ├── go.just         # Go module (go::build, go::test)
    ├── docker.just     # Docker module (docker::build, docker::push)
    └── lua.just        # Lua module (lua::install, lua::check)

Bootstrapping a New Repo

1. Copy assets/dev to project root, make executable: chmod +x dev
2. Copy assets/just/ directory to project root
3. Create root justfile with imports and modules
4. Edit just/dev.just with project-specific setup commands
5. Add additional .just modules as needed

Quick Reference

Root Justfile (Recommended Pattern)

Put everything in root justfile for tab completion to work:

Copy# justfile (root)
set quiet
set dotenv-load

# Imports: merged into root namespace
import 'just/dev.just'

# Modules: namespaced with :: syntax (specify path)
mod go 'just/go.just'           # go::build, go::test
mod docker 'just/docker.just'   # docker::build, docker::push
mod lua 'just/lua.just'         # lua::install, lua::check

default:
    just --list

Module Example

Copy# just/go.just - called as go::build, go::test, etc.
VERSION := `git describe --tags --always 2>/dev/null || echo "dev"`
BIN_DIR := env_var("PWD") / "bin"

# Build the application
[group('go')]
build tool:
    @mkdir -p {{BIN_DIR}}
    go build -o {{BIN_DIR}}/{{tool}} .

# Run tests
[group('go')]
test tool:
    go test -race -cover ./...

# Run linter
[group('go')]
lint:
    golangci-lint run

Import vs Module

Rule of thumb: Use import only for dev.just. Use mod for everything else.

Common Dev Module (Imported)

Copy# just/dev.just - Imported (no namespace) for common recipes

# Bootstrap the development environment
dev:
    echo "Installing dependencies..."
    # npm install / pip install -r requirements.txt / cargo build
    echo "Done!"

# Clean build artifacts
clean:
    rm -rf dist/ build/ target/

Tool Module Example

Copy# just/lua.just - Called as lua::install, lua::check, etc.
lua_version := env("LUA_VERSION", "5.4.6")
prefix := env("PREFIX", "/usr/local")

# Install complete lua environment
[group('lua')]
default: check install
    echo "Lua environment setup complete"

# Check current installation status
[group('lua')]
check:
    command -v lua >/dev/null 2>&1 || echo "lua not found"

# Install all components
[group('lua')]
install: install-deps install-lua install-luarocks
    echo "Lua installation complete"

# Clean build artifacts
[group('lua')]
clean:
    rm -rf /tmp/lua-build/*

Listing Recipes

Copyjust --list                    # Shows modules collapsed
just --list --list-submodules  # Shows all module recipes expanded
just lua::                     # Tab-complete shows lua recipes

Shell Completions Setup

When setting up just for a user, check if shell completions are configured and set them up if missing.

Detection

Check if _just completion function exists:

Copy# For zsh
type _just &>/dev/null

# For bash
type _just &>/dev/null || complete -p just &>/dev/null

Setup Steps

If completions don't exist:

1. Create completions directory (respects XDG):

   CopyJUST_CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/just"
   mkdir -p "$JUST_CONFIG_DIR"
   

2. Generate completions file:

   Copy# For zsh
   just --completions zsh > "$JUST_CONFIG_DIR/completions.zsh"
   
   # For bash
   just --completions bash > "$JUST_CONFIG_DIR/completions.bash"
   

3. Add sourcing to shell rc (if not already present):

   For zsh (~/.zshrc):

   Copy# just completions
   if command -v just &>/dev/null; then
       [[ -f "${XDG_CONFIG_HOME:-$HOME/.config}/just/completions.zsh" ]] && source "${XDG_CONFIG_HOME:-$HOME/.config}/just/completions.zsh"
   fi
   

   For bash (~/.bashrc):

   Copy# just completions
   if command -v just &>/dev/null; then
       [[ -f "${XDG_CONFIG_HOME:-$HOME/.config}/just/completions.bash" ]] && source "${XDG_CONFIG_HOME:-$HOME/.config}/just/completions.bash"
   fi
   

Verification

After adding, verify with:

Copysource ~/.zshrc  # or ~/.bashrc
type _just  # should show completion function

References

Detailed syntax and patterns in references/: