Ritefile Schema Reference

This page documents every property of the Ritefile schema (version 3) and the types it accepts. The shape is near-identical to go-task's Taskfile v3 schema; the semantics are where rite differs — see precedence for the eight-tier variable model and migration for the five user-visible breaks.

Note — a hosted JSON schema is not yet published. We'll serve one at clintmod.github.io/rite/schema.json once the docs site has a stable URL. In the meantime, point your YAML language server at go-task's schema — the Ritefile shape is a subset that validates fine against it. Pages like "included-file top-level vars follow first-in-wins" are runtime rules the schema can't express.

Root Schema

The root Ritefile schema defines the structure of your main Ritefile.yml.

`version`

Type: string or number
Required: Yes
Valid values: "3", 3, or any valid semver string
Description: Version of the Ritefile schema

yaml

version: '3'

`output`

Type: string or object
Default: interleaved
Options: interleaved, group, prefixed
Description: Controls how task output is displayed

yaml

# Simple string format
output: group

# Advanced object format
output:
  group:
    begin: "::group::{{.RITE_NAME}}"
    end: "::endgroup::"
    error_only: false

`method`

Type: string
Default: checksum
Options: checksum, timestamp, none
Description: Default method for checking if tasks are up-to-date

yaml

method: timestamp

`includes`

Type: map[string]Include
Description: Include other Ritefiles

yaml

includes:
  # Simple string format
  docs: ./Ritefile.yml

  # Full object format
  backend:
    taskfile: ./backend
    dir: ./backend
    optional: false
    flatten: false
    internal: false
    aliases: [api]
    excludes: [internal-task]
    vars:
      SERVICE_NAME: backend
    checksum: abc123...

`vars`

Type: map[string]Variable
Description: Global variables available to all tasks

yaml

vars:
  # Simple values
  APP_NAME: myapp
  VERSION: 1.0.0
  DEBUG: true
  PORT: 8080
  FEATURES: [auth, logging]

  # Dynamic variables
  COMMIT_HASH:
    sh: git rev-parse HEAD

  # Variable references
  BUILD_VERSION:
    ref: .VERSION

  # Map variables
  CONFIG:
    map:
      database: postgres
      cache: redis

`env`

Type: map[string]Variable
Description: Global environment variables

yaml

env:
  NODE_ENV: production
  DATABASE_URL:
    sh: echo $DATABASE_URL

`tasks`

Type: map[string]Task
Description: Task definitions

yaml

tasks:
  # Simple string format
  hello: echo "Hello World"

  # Array format
  build:
    - go mod tidy
    - go build ./...

  # Full object format
  deploy:
    desc: Deploy the application
    cmds:
      - ./scripts/deploy.sh

`silent`

Type: bool
Default: false
Description: Suppress task name and command output by default

yaml

silent: true

`dotenv`

Type: []string
Description: Load environment variables from .env files. When the same variable is defined in multiple files, the first file in the list takes precedence.

yaml

dotenv:
  - .env.local # Highest priority
  - .env # Lowest priority

`run`

Type: string
Default: always
Options: always, once, when_changed
Description: Default execution behavior for tasks

yaml

run: once

`interval`

Type: string
Default: 100ms
Pattern: ^[0-9]+(?:m|s|ms)$
Description: Watch interval for file changes

yaml

interval: 1s

`set`

Type: []string
Options: allexport, a, errexit, e, noexec, n, noglob, f, nounset, u, xtrace, x, pipefail
Description: POSIX shell options for all commands

yaml

set: [errexit, nounset, pipefail]

`shopt`

Type: []string
Options: expand_aliases, globstar, nullglob
Description: Bash shell options for all commands

yaml

shopt: [globstar]

Include

Configuration for including external Ritefiles.

`taskfile`

Type: string
Required: Yes
Description: Path to the Ritefile or directory to include

yaml

includes:
  backend: ./backend/Ritefile.yml
  # Shorthand for above
  frontend: ./frontend

`dir`

Type: string
Description: Working directory for included tasks

yaml

includes:
  api:
    taskfile: ./api
    dir: ./api

`optional`

Type: bool
Default: false
Description: Don't error if the included file doesn't exist

yaml

includes:
  optional-tasks:
    taskfile: ./optional.yml
    optional: true

`flatten`

Type: bool
Default: false
Description: Include tasks without namespace prefix

yaml

includes:
  common:
    taskfile: ./common.yml
    flatten: true

`internal`

Type: bool
Default: false
Description: Hide included tasks from command line and --list

yaml

includes:
  internal:
    taskfile: ./internal.yml
    internal: true

`aliases`

Type: []string
Description: Alternative names for the namespace

yaml

includes:
  database:
    taskfile: ./db.yml
    aliases: [db, data]

`excludes`

Type: []string
Description: Tasks to exclude from inclusion

yaml

includes:
  shared:
    taskfile: ./shared.yml
    excludes: [internal-setup, debug-only]

`vars`

Type: map[string]Variable
Description: Variables to pass to the included Ritefile

yaml

includes:
  deploy:
    taskfile: ./deploy.yml
    vars:
      ENVIRONMENT: production

`checksum`

Type: string
Description: Expected checksum of the included file

yaml

includes:
  shared:
    taskfile: ./vendored/shared.yml
    checksum: c153e97e0b3a998a7ed2e61064c6ddaddd0de0c525feefd6bba8569827d8efe9

Variable

Variables support multiple types and can be static values, dynamic commands, references, or maps.

Static Variables

yaml

vars:
  # String
  APP_NAME: myapp
  # Number
  PORT: 8080
  # Boolean
  DEBUG: true
  # Array
  FEATURES: [auth, logging, metrics]
  # Null
  OPTIONAL_VAR: null

Dynamic Variables (`sh`)

yaml

vars:
  COMMIT_HASH:
    sh: git rev-parse HEAD
  BUILD_TIME:
    sh: date -u +"%Y-%m-%dT%H:%M:%SZ"

Variable References (`ref`)

yaml

vars:
  BASE_VERSION: 1.0.0
  FULL_VERSION:
    ref: .BASE_VERSION

Map Variables (`map`)

yaml

vars:
  CONFIG:
    map:
      database:
        host: localhost
        port: 5432
      cache:
        type: redis
        ttl: 3600

Variable Ordering

Variables can reference previously defined variables:

yaml

vars:
  GREETING: Hello
  TARGET: World
  MESSAGE: '{{.GREETING}} {{.TARGET}}!'

Task

Individual task configuration with multiple syntax options.

Simple Task Formats

yaml

tasks:
  # String command
  hello: echo "Hello World"

  # Array of commands
  build:
    - go mod tidy
    - go build ./...

  # Object with cmd shorthand
  test:
    cmd: go test ./...

Task Properties

`cmds`

Type: []Command
Description: Commands to execute

yaml

tasks:
  build:
    cmds:
      - go build ./...
      - echo "Build complete"

`cmd`

Type: string
Description: Single command (alternative to cmds)

yaml

tasks:
  test:
    cmd: go test ./...

`deps`

Type: []Dependency
Description: Tasks to run before this task

yaml

tasks:
  # Simple dependencies
  deploy:
    deps: [build, test]
    cmds:
      - ./deploy.sh

  # Dependencies with variables
  advanced-deploy:
    deps:
      - task: build
        vars:
          ENVIRONMENT: production
      - task: test
        vars:
          COVERAGE: true
    cmds:
      - ./deploy.sh

  # Silent dependencies
  main:
    deps:
      - task: setup
        silent: true
    cmds:
      - echo "Main task"

  # Loop dependencies
  test-all:
    deps:
      - for: [unit, integration, e2e]
        task: test
        vars:
          TEST_TYPE: '{{.ITEM}}'
    cmds:
      - echo "All tests completed"

`desc`

Type: string
Description: Short description shown in --list

yaml

tasks:
  test:
    desc: Run unit tests
    cmds:
      - go test ./...

`summary`

Type: string
Description: Detailed description shown in --summary

yaml

tasks:
  deploy:
    desc: Deploy to production
    summary: |
      Deploy the application to production environment.
      This includes building, testing, and uploading artifacts.

`prompt`

Type: string or []string
Description: Prompts shown before task execution

yaml

tasks:
  # Single prompt
  deploy:
    prompt: "Deploy to production?"
    cmds:
      - ./deploy.sh

  # Multiple prompts
  deploy-multi:
    prompt:
      - "Are you sure?"
      - "This will affect live users!"
    cmds:
      - ./deploy.sh

`aliases`

Type: []string
Description: Alternative names for the task

yaml

tasks:
  build:
    aliases: [compile, make]
    cmds:
      - go build ./...

`method`

Type: string
Default: checksum
Options: checksum, timestamp, none
Description: Method for checking if the task is up-to-date. Refer to the method root property for details.

yaml

tasks:
  build:
    sources:
      - go.mod
    method: timestamp

`sources`

Type: []string or []Glob
Description: Source files to monitor for changes

yaml

tasks:
  build:
    sources:
      - '**/*.go'
      - go.mod
      # With exclusions
      - exclude: '**/*_test.go'
    cmds:
      - go build ./...

`generates`

Type: []string or []Glob
Description: Files generated by this task

yaml

tasks:
  build:
    sources: ['**/*.go']
    generates:
      - './app'
      - exclude: '*.debug'
    cmds:
      - go build -o app ./cmd

`status`

Type: []string
Description: Commands to check if task should run

yaml

tasks:
  install-deps:
    status:
      - test -f node_modules/.installed
    cmds:
      - npm install
      - touch node_modules/.installed

`preconditions`

Type: []Precondition
Description: Conditions that must be met before running

yaml

tasks:
  # Simple precondition (shorthand)
  build:
    preconditions:
      - test -d ./src
    cmds:
      - go build ./...

  # Preconditions with custom messages
  deploy:
    preconditions:
      - sh: test -n "$API_KEY"
        msg: 'API_KEY environment variable is required'
      - sh: test -f ./app
        msg: "Application binary not found. Run 'task build' first."
    cmds:
      - ./deploy.sh

`if`

Type: string
Description: Shell command to conditionally execute the task. If the command exits with a non-zero code, the task is skipped (not failed).

yaml

tasks:
  # Task only runs in CI environment
  deploy:
    if: '[ "$CI" = "true" ]'
    cmds:
      - ./deploy.sh

  # Using Go template expressions
  build-prod:
    if: '{{eq .ENV "production"}}'
    cmds:
      - go build -ldflags="-s -w" ./...

`dir`

Type: string
Description: The directory in which this task should run
Default: If the task is in the root Ritefile, the default dir is ROOT_DIR. For included Ritefiles, the default dir is the value specified in their respective includes.*.dir field (if any).

yaml

tasks:
  current-dir:
    dir: '{{.USER_WORKING_DIR}}'
    cmd: pwd

`requires`

Type: Requires
Description: Required variables with optional enum validation

yaml

tasks:
  deploy:
    requires:
      vars: [API_KEY, ENVIRONMENT]
    cmds:
      - ./deploy.sh

  advanced-deploy:
    requires:
      vars:
        - API_KEY
        - name: ENVIRONMENT
          enum: [development, staging, production]
        - name: LOG_LEVEL
          enum: [debug, info, warn, error]
    cmds:
      - echo "Deploying to {{.ENVIRONMENT}} with log level {{.LOG_LEVEL}}"
      - ./deploy.sh


  # Requirements with enum from variable reference
  reusable-deploy:
    requires:
      vars:
        - name: ENVIRONMENT
          enum:
            ref: .ALLOWED_ENVS
    cmds:
      - ./deploy.sh

See the SPEC for information on enabling interactive prompts for missing required variables.

`watch`

Type: bool
Default: false
Description: Automatically run task in watch mode

yaml

tasks:
  dev:
    watch: true
    cmds:
      - npm run dev

`platforms`

Type: []string
Description: Platforms where this task should run

yaml

tasks:
  windows-build:
    platforms: [windows]
    cmds:
      - go build -o app.exe ./cmd

  unix-build:
    platforms: [linux, darwin]
    cmds:
      - go build -o app ./cmd

Command

Individual command configuration within a task.

Basic Commands

yaml

tasks:
  example:
    cmds:
      - echo "Simple command"
      - ls -la

Command Object

yaml

tasks:
  example:
    cmds:
      - cmd: echo "Hello World"
        silent: true
        ignore_error: false
        platforms: [linux, darwin]
        set: [errexit]
        shopt: [globstar]

Task References

yaml

tasks:
  example:
    cmds:
      - task: other-task
        vars:
          PARAM: value
        silent: false

Deferred Commands

yaml

tasks:
  with-cleanup:
    cmds:
      - echo "Starting work"
      # Deferred command string
      - defer: echo "Cleaning up"
      # Deferred task reference
      - defer:
          task: cleanup-task
          vars:
            CLEANUP_MODE: full

For Loops

Loop Over List

yaml

tasks:
  greet-all:
    cmds:
      - for: [alice, bob, charlie]
        cmd: echo "Hello {{.ITEM}}"

Loop Over Sources/Generates

yaml

tasks:
  process-files:
    sources: ['*.txt']
    cmds:
      - for: sources
        cmd: wc -l {{.ITEM}}
      - for: generates
        cmd: gzip {{.ITEM}}

Loop Over Variable

yaml

tasks:
  process-items:
    vars:
      ITEMS: 'item1,item2,item3'
    cmds:
      - for:
          var: ITEMS
          split: ','
          as: CURRENT
        cmd: echo "Processing {{.CURRENT}}"

Loop Over Matrix

yaml

tasks:
  test-matrix:
    cmds:
      - for:
          matrix:
            OS: [linux, windows, darwin]
            ARCH: [amd64, arm64]
        cmd: echo "Testing {{.ITEM.OS}}/{{.ITEM.ARCH}}"

Loop in Dependencies

yaml

tasks:
  build-all:
    deps:
      - for: [frontend, backend, worker]
        task: build
        vars:
          SERVICE: '{{.ITEM}}'

Conditional Commands

Use if to conditionally execute a command. If the shell command exits with a non-zero code, the command is skipped.

yaml

tasks:
  build:
    cmds:
      # Only run in production
      - cmd: echo "Optimizing for production"
        if: '[ "$ENV" = "production" ]'
      # Using Go templates
      - cmd: echo "Feature enabled"
        if: '{{eq .ENABLE_FEATURE "true"}}'
      # Inside for loops (evaluated per iteration)
      - for: [a, b, c]
        cmd: echo "processing {{.ITEM}}"
        if: '[ "{{.ITEM}}" != "b" ]'

Shell Options

Set Options

Available set options for POSIX shell features:

allexport / a - Export all variables
errexit / e - Exit on error
noexec / n - Read commands but don't execute
noglob / f - Disable pathname expansion
nounset / u - Error on undefined variables
xtrace / x - Print commands before execution
pipefail - Pipe failures propagate

yaml

# Global level
set: [errexit, nounset, pipefail]

tasks:
  debug:
    # Task level
    set: [xtrace]
    cmds:
      - cmd: echo "This will be traced"
        # Command level
        set: [noexec]

Shopt Options

Available shopt options for Bash features:

expand_aliases - Enable alias expansion
globstar - Enable ** recursive globbing
nullglob - Null glob expansion

yaml

# Global level
shopt: [globstar]

tasks:
  find-files:
    # Task level
    shopt: [nullglob]
    cmds:
      - cmd: ls **/*.go
        # Command level
        shopt: [globstar]

Ritefile Schema Reference ​

Root Schema ​

version ​

output ​

method ​

includes ​

vars ​

env ​

tasks ​

silent ​

dotenv ​

run ​

interval ​

set ​

shopt ​

Include ​

taskfile ​

dir ​

optional ​

flatten ​

internal ​

aliases ​

excludes ​

vars ​

checksum ​

Variable ​

Static Variables ​

Dynamic Variables (sh) ​

Variable References (ref) ​

Map Variables (map) ​

Variable Ordering ​

Task ​

Simple Task Formats ​

Task Properties ​

cmds ​

cmd ​

deps ​

desc ​

summary ​

prompt ​

aliases ​

method ​

sources ​

generates ​

status ​

preconditions ​

if ​

dir ​

requires ​

watch ​

platforms ​

Command ​

Basic Commands ​

Command Object ​

Task References ​

Deferred Commands ​

For Loops ​

Loop Over List ​

Loop Over Sources/Generates ​

Loop Over Variable ​

Loop Over Matrix ​

Loop in Dependencies ​

Conditional Commands ​

Shell Options ​

Set Options ​

Shopt Options ​

Ritefile Schema Reference

Root Schema

`version`

`output`

`method`

`includes`

`vars`

`env`

`tasks`

`silent`

`dotenv`

`run`

`interval`

`set`

`shopt`

Include

`taskfile`

`dir`

`optional`

`flatten`

`internal`

`aliases`

`excludes`

`vars`

`checksum`

Variable

Static Variables

Dynamic Variables (`sh`)

Variable References (`ref`)

Map Variables (`map`)

Variable Ordering

Task

Simple Task Formats

Task Properties

`cmds`

`cmd`

`deps`

`desc`

`summary`

`prompt`

`aliases`

`method`

`sources`

`generates`

`status`

`preconditions`

`if`

`dir`

`requires`

`watch`

`platforms`

Command

Basic Commands

Command Object

Task References

Deferred Commands

For Loops

Loop Over List

Loop Over Sources/Generates

Loop Over Variable

Loop Over Matrix

Loop in Dependencies

Conditional Commands

Shell Options

Set Options

Shopt Options