Blocks

A playbook is made up of four block types. Each has a distinct role in defining how a run behaves.

errand block

The errand block sets playbook-level configuration. It is optional and can appear at most once across all .ern files.

errand {
  working_dir = "<path>"
}

Attributes

working_dir

string

The default working directory for all tasks in the playbook. Tasks with their own working_dir override this value. Relative paths are resolved from the directory where errand was invoked.

Example

errand {
  working_dir = "./service/api"
}

task "test" {
  commands = ["go test ./..."]
}

task "build" {
  depends_on = [task.test]
  commands   = ["go build -o bin/api ./cmd/api"]
}

Both test and build run from ./service/api without repeating working_dir in each task.

Notes

If no errand block is declared, tasks run from the directory where errand was invoked unless they specify their own working_dir.
Declaring errand more than once is an error.

variable block

Variables are named inputs. Declare them in the playbook and pass values at run time with --var. Reference them as var.<name>.

variable "<name>" {
  description = "<text>"
  type        = <type>
  default     = <value>
}

All attributes are optional. A variable with no default is required: Errand reports an error if no value is provided.

Attributes

description

string

A human-readable description shown in error messages.

type

type constraint

A type constraint. When set, Errand validates and converts the provided value. See types for all available types.

default

any

The value used when no --var flag is passed. Must be compatible with type when both are set.

Passing values

errand run deploy --var env=production --var replicas=3

Multiple --var flags are supported. Values are strings on the command line and converted to the declared type automatically.

Examples

Required variable, no default means it must be supplied:

variable "registry" {
  description = "Container registry host"
  type        = string
}

task "push" {
  commands = ["docker push ${var.registry}/myapp:latest"]
}

Variable with a default:

variable "port" {
  description = "Port the server listens on"
  type        = number
  default     = 8080
}

task "run" {
  commands = ["./bin/server --port ${var.port}"]
}

Object variable, structured inputs keep related values together:

variable "db" {
  description = "Database connection settings"
  type = object({
    host = string
    port = optional(number, 5432)
    name = string
  })
}

task "migrate" {
  commands = [
    "psql -h ${var.db.host} -p ${var.db.port} -d ${var.db.name} -f schema.sql",
  ]
}

Pass an object from the command line:

errand run migrate --var 'db={ host = "db.prod", name = "appdb" }'

The port field is omitted, so its default 5432 applies. Boolean variable used in a conditional command:

variable "verbose" {
  type    = bool
  default = false
}

task "test" {
  commands = [
    "go test ${var.verbose ? \"-v\" : \"\"} ./...",
  ]
}

Notes

Variable names must be unique across all .ern files in the playbook.
Access object fields with dot notation: var.db.host.
Access list elements by index: var.services[0].

computed block

A computed block evaluates an expression at runtime and makes the result available as computed.<name>. Use it to derive values from variables, the environment, or built-in functions without duplicating logic across tasks.

computed "<name>" {
  description = "<text>"
  expression  = <expression>
}

expression is required. description is optional.

Attributes

description

string

A human-readable description of the computed value.

expression

required

The expression to evaluate. Can reference variables (var.<name>), call built-in functions, and combine values with string interpolation.

Evaluation order

Computed blocks are evaluated before tasks run, in dependency order. If a computed block references a variable, that variable is resolved first automatically. If two computed blocks reference each other, Errand reports a cycle error.

Examples

Read from the environment with a fallback:

computed "registry" {
  description = "Container registry from CI environment"
  expression  = env("CI_REGISTRY", "registry.example.com")
}

task "push" {
  commands = ["docker push ${computed.registry}/myapp:latest"]
}

Build a value from multiple inputs:

variable "image" {
  type    = string
  default = "myapp"
}

variable "tag" {
  type = string
}

computed "full_image" {
  description = "Fully qualified image reference"
  expression  = "${env("CI_REGISTRY", "registry.example.com")}/${var.image}:${var.tag}"
}

task "build" {
  commands = ["docker build -t ${computed.full_image} ."]
}

task "push" {
  depends_on = [task.build]
  commands   = ["docker push ${computed.full_image}"]
}

Chain computed values: image_tag depends on version, so Errand evaluates version first:

computed "version" {
  expression = trimspace(file("VERSION"))
}

computed "image_tag" {
  expression = "${var.app}-${computed.version}"
}

Notes

Computed names must be unique across all .ern files in the playbook.
Computed values are read-only. Tasks cannot modify them.

task block

A task is a named group of shell commands. Tasks can depend on other tasks, run conditionally, and be scoped to a specific directory.

task "<name>" {
  description = "<text>"
  working_dir = "<path>"
  condition   = <boolean expression>
  depends_on  = [<task references>]
  commands    = [<string expressions>]
}

Only commands is required.

Attributes

description

string

A human-readable description of what the task does.

working_dir

string

The directory to run commands in. Overrides the playbook-level working_dir from the errand block. Relative paths are resolved from the directory where errand was invoked.

condition

boolean expression

A boolean expression. When it evaluates to false, the task is skipped. Tasks that depend on a skipped task are also skipped.

depends_on

list of task references

An explicit list of tasks that must complete before this task runs. Write each as task.<name>. Errand also infers dependencies from expression references in commands and condition.

commands

list of string expressions

required

Shell commands to execute in order. Each command is a string expression and can use variables, computed values, and built-in functions. Commands stop at the first failure.

Examples

Task with dependencies, Errand runs test and lint before build:

task "lint" {
  commands = ["golangci-lint run ./..."]
}

task "test" {
  commands = ["go test ./..."]
}

task "build" {
  description = "Compile the binary"
  depends_on  = [task.lint, task.test]
  commands    = ["go build -o bin/app ./cmd/app"]
}

Conditional task, skip when a lock file is absent:

task "install" {
  description = "Install dependencies"
  condition   = fileexists("package-lock.json")
  commands    = ["npm ci"]
}

Aggregate task, runs dependencies only, no commands of its own:

task "ci" {
  description = "Full CI pipeline"
  depends_on  = [task.lint, task.test, task.build]
  commands    = []
}

Default task

When you call errand run with no task name, Errand runs the task named default:

task "default" {
  depends_on = [task.test, task.build]
  commands   = []
}

Notes

Task names must be unique across all .ern files in the playbook.
Commands run inside a built-in POSIX-compatible shell interpreter. No external shell is required, including on Windows.
If a command fails, remaining commands in the same task are skipped and the task is marked as failed.
Tasks that do not depend on a failed task continue to run normally.

Getting started

Playbook

Syntax

CLI

errand block

Attributes

Example

Notes

variable block

Attributes

Passing values

Examples

Notes

computed block

Attributes

Evaluation order

Examples

Notes

task block

Attributes

Examples

Default task

Notes

​errand block

​Attributes

​Example

​Notes

​variable block

​Attributes

​Passing values

​Examples

​Notes

​computed block

​Attributes

​Evaluation order

​Examples

​Notes

​task block

​Attributes

​Examples

​Default task

​Notes

errand block

Attributes

Example

Notes

variable block

Attributes

Passing values

Examples

Notes

computed block

Attributes

Evaluation order

Examples

Notes

task block

Attributes

Examples

Default task

Notes