Configuration Guide¶

This guide covers all the configuration options and features of RunLy.

File Discovery¶

RunLy automatically searches for configuration files in the following order:

justfile
Justfile
.justfile
runly.yaml
runly.yml

You can also specify a custom file with the -f flag:

runly -f my-tasks.yml build

Justfile Syntax¶

RunLy supports the standard justfile syntax with some enhancements.

Basic Command Structure¶

command_name parameter1 parameter2="default_value":
    command to execute
    another command

Variables¶

Variables are defined at the top of the file:

# Simple variables
name := "myproject"
version := "1.0.0"

# Variables with default values from environment
port := env_var_or_default("PORT", "8000")

Variable Expansion¶

RunLy supports multiple variable expansion formats:

name := "myproject"

example:
    echo "{{name}}"        # Just/RunLy style (preferred)
    echo "${name}"         # Shell variable style
    echo "$name"           # Short shell style

Command Parameters¶

Commands can accept parameters with optional default values:

# No parameters
test:
    pytest tests/

# Required parameter
deploy env:
    ./deploy.sh {{env}}

# Optional parameter with default
build target="debug":
    cargo build --profile {{target}}

Command Dependencies¶

Commands can depend on other commands:

# Simple dependency
deploy: build
    ./deploy.sh

# Multiple dependencies
ci: test lint security-check
    echo "All checks passed"

Default Commands¶

Mark a command as default with an asterisk:

# This runs when you just type 'runly'
*test:
    pytest tests/

build:
    python setup.py build

YAML Configuration¶

For more structured configuration, you can use YAML format:

Basic Structure¶

variables:
  name: "myproject"
  version: "1.0.0"

commands:
  test:
    script: |
      pytest tests/
    description: "Run the test suite"

  build:
    script: |
      python setup.py build
    description: "Build the project"
    dependencies: ["test"]

Command Parameters in YAML¶

commands:
  deploy:
    script: |
      ./deploy.sh {{env}}
    description: "Deploy to environment"
    parameters:
      env:
        required: true
        description: "Target environment (dev, staging, prod)"

Environment Variables¶

In Justfiles¶

# Use environment variables with defaults
port := env_var_or_default("PORT", "8000")
debug := env_var_or_default("DEBUG", "false")

serve:
    @echo "Starting server on port {{port}}"
    python app.py --port {{port}} --debug {{debug}}

Best Practices¶

Use Meaningful Command Names

# Good
test-unit:
    pytest tests/unit/

# Avoid
t:
    pytest tests/

Document Parameters

# Deploy to specified environment
# Usage: runly deploy <env>
# env: target environment (dev, staging, prod)
deploy env:
    ./deploy.sh {{env}}

Use Dependencies Wisely

# Build depends on tests passing
build: test
    python setup.py build

# Deploy depends on build
deploy env: build
    ./deploy.sh {{env}}

Use Variables for Reusability

app_name := "myapp"
version := "1.0.0"
docker_tag := app_name + ":" + version

docker-build:
    docker build -t {{docker_tag}} .

docker-push:
    docker push {{docker_tag}}