Skip to main content

Configuration Reference

This page provides a complete reference for Pace configuration files (.pace files).

File Structure​

Pace configuration files use a simple, human-readable syntax. The file typically named config.pace should be placed in your project root.

# Comments start with #

# Define variables
var variable_name = "value"

# Set default task
default task_name

# Create task aliases
alias shortname taskname

# Define tasks
task task_name {
    # Task properties...
}

# Define hooks
hook hook_name {
    # Hook properties...
}

Variables​

Variables allow you to define reusable values throughout your configuration.

Syntax​

var variable_name = "value"

Variable Interpolation​

Variables can be referenced using ${variable_name} or $variable_name syntax:

var output = "bin/myapp"
var version = "1.0.0"

task build {
    command "go build -ldflags '-X main.Version=${version}' -o ${output} main.go"
}

Environment Variables​

Environment variables from your system are automatically available:

task build {
    command "echo Building on ${HOSTNAME}"
}

Default Task​

Set the default task that runs when you execute pace run without arguments:

default build

Aliases​

Create shortcuts for task names using the standalone alias keyword:

alias b build
alias t test
alias d deploy

Alternatively, you can define aliases directly in the task definition:

task build [b] {
    description "Build the application"
    command "go build -o bin/app main.go"
}

task test [t] {
    description "Run tests"
    command "go test ./..."
}

Usage:

pace run b  # same as: pace run build
pace run t  # same as: pace run test

Tasks​

Tasks are the main building blocks of your Pace configuration.

Basic Task​

task build {
    description "Build the application"
    command "go build -o bin/app main.go"
}

Task Properties​

description (string)​

Human-readable description of what the task does.

task build {
    description "Build the application for production"
}

command (string, required)​

The command to execute. Can span multiple lines using triple quotes.

task build {
    command "go build -o bin/app main.go"
}

task multi {
    command """
        echo "Step 1"
        echo "Step 2"
        go build
    """
}

inputs (array of strings)​

File patterns that this task depends on. Used for caching and file watching.

task build {
    inputs ["**/*.go", "go.mod", "go.sum"]
}

Supports glob patterns:

  • **/*.go - All Go files recursively
  • src/**/*.ts - All TypeScript files in src/
  • *.json - All JSON files in current directory

outputs (array of strings)​

Files or patterns that this task produces. Used for caching.

task build {
    outputs ["bin/app", "bin/app.exe"]
}

cache (boolean)​

Enable smart caching. Task will be skipped if inputs haven't changed since last successful run.

task build {
    cache true
    inputs ["**/*.go"]
    outputs ["bin/app"]
}

Default: false

depends-on (array of strings)​

Tasks that must complete before this task runs. Dependencies are executed in order.

task deploy {
    depends-on [test, build]
}

Note: You can use either identifiers or strings in arrays: [test, build] or ["test", "build"]

requires (array of strings)​

Hooks or tasks to run before this task.

task build {
    requires [test, lint]
}

triggers (array of strings)​

Hooks or tasks to run after this task completes.

task build {
    triggers [notify]
}

on_success (array of strings)​

Hooks or tasks to run only if this task succeeds.

task deploy {
    on_success [notify_success]
}

on_failure (array of strings)​

Hooks or tasks to run only if this task fails.

task deploy {
    on_failure [rollback, notify_failure]
}

env (map of strings)​

Environment variables to set for this task.

task build {
    env {
        CGO_ENABLED = "0"
        GOOS = "linux"
        GOARCH = "amd64"
    }
}

working_dir (string)​

Directory to run the command in.

task frontend {
    working_dir "frontend"
    command "npm run build"
}

timeout (string)​

Maximum time to allow the task to run. Supports duration suffixes.

task build {
    timeout "10m"
}

Supported units:

  • s - seconds
  • m - minutes
  • h - hours

Examples: 30s, 5m, 1h30m

retry (integer)​

Number of times to retry if the task fails.

task deploy {
    retry 3
}

Default: 0 (no retries)

retry_delay (string)​

Time to wait between retries.

task deploy {
    retry 3
    retry_delay "5s"
}

parallel (boolean)​

Whether dependencies can run in parallel.

task all {
    depends-on [backend, frontend]
    parallel true  # Run backend and frontend simultaneously
}

Default: false

silent (boolean)​

Suppress command output.

task quiet {
    silent true
}

Default: false

continue_on_error (boolean)​

Continue execution even if this task fails.

task optional {
    continue_on_error true
}

Default: false

watch (boolean)​

Automatically watch input files and re-run on changes.

task dev {
    watch true
    inputs ["**/*.go"]
    command "go run main.go"
}

Default: false

args (object)​

Define arguments that can be passed to the task.

task greet {
    args {
        required ["name"]
        optional ["greeting"]
    }
    command "echo '${greeting:-Hello}, $name!'"
}

Usage:

pace run greet --name=World --greeting=Hi

Positional arguments are also supported:

task echo {
    command "echo $1 $2 $3"
}

Usage:

pace run echo hello world test

Hooks​

Hooks are lightweight tasks designed for setup, cleanup, or other auxiliary operations.

Basic Hook​

hook format {
    description "Format code"
    command "gofmt -s -w ."
}

Hook Properties​

Hooks support a subset of task properties:

  • description - Description of the hook
  • command - Command to execute (required)
  • env - Environment variables
  • working_dir - Working directory

Hooks do not support:

  • Dependencies
  • Caching
  • Retries
  • Arguments
  • Before/after hooks

Globals​

Define global settings that apply to all tasks.

globals {
    "env" {
        "GO_ENV" "production"
    }
}

Imports​

Import configuration from other files:

import "tasks/common.pace"
import "tasks/deploy.pace"

Imported configurations are merged with the current file. Local definitions take precedence.

Complete Example​

# Variables
var app_name = "myapp"
var version = "1.0.0"
var build_dir = "bin"

# Default task
default build

# Hooks
hook format {
    description "Format Go code"
    command "gofmt -s -w ."
}

hook lint {
    description "Run linter"
    command "golangci-lint run"
}

# Tasks
task test [t] {
    description "Run all tests"
    command "go test -v ./..."
    inputs [**/*.go]
    timeout "5m"
    cache true
}

task build [b] {
    description "Build the application"
    command "go build -ldflags '-X main.Version=${version}' -o ${build_dir}/${app_name} main.go"
    requires [test, format, lint]
    inputs [**/*.go, go.mod, go.sum]
    outputs [${build_dir}/${app_name}]
    cache true
    env {
        CGO_ENABLED = "0"
    }
}

task docker {
    description "Build Docker image"
    command "docker build -t ${app_name}:${version} ."
    depends-on [build]
    inputs [Dockerfile, ${build_dir}/${app_name}]
}

task deploy [d] {
    description "Deploy to production"
    command "./scripts/deploy.sh ${version}"
    depends-on [docker]
    on_success [notify_success]
    on_failure [notify_failure, rollback]
    retry 2
    retry_delay "10s"
    timeout "15m"
}

hook notify_success {
    command "echo 'Deployment successful!'"
}

hook notify_failure {
    command "echo 'Deployment failed!'"
}

hook rollback {
    command "./scripts/rollback.sh"
}

Comments​

Comments start with # and continue to the end of the line:

# This is a comment
task build {  # Inline comments are also supported
    command "go build"
}

String Literals​

Pace supports both single-line and multi-line strings:

# Single-line
task single {
    command "echo 'hello'"
}

# Multi-line (using triple quotes)
task multi {
    command """
        echo "Line 1"
        echo "Line 2"
        echo "Line 3"
    """
}

Boolean Values​

Use true or false (lowercase):

task build {
    cache true
    silent false
    parallel true
}

Numbers​

Numbers can be integers or include duration suffixes:

task build {
    retry 3
    timeout "5m"
    retry_delay "30s"
}

Next Steps​