Tasks

A task is the smallest execution unit in Meriadoc — a named list of shell commands with optional environment variables, preconditions, and failure handlers.

Basic task

version: v1

tasks:
  build:
    description: "Build the project"
    cmds:
      - cargo build --release

Run it:

meriadoc run task build
# or shorter:
meriadoc task build

Environment variables

Declare typed env vars that Meriadoc will prompt for, validate, and inject:

tasks:
  deploy:
    cmds:
      - ./deploy.sh
    env:
      ENVIRONMENT:
        type: choice
        options: [dev, staging, prod]
        default: dev
      API_KEY:
        type: secret
        required: true
      DEBUG:
        type: boolean
        default: "false"

Override from the CLI:

meriadoc run task deploy --env ENVIRONMENT=staging

Variable types

Variable interpolation

Use ${VAR} or $VAR in commands. Meriadoc resolves them before execution:

tasks:
  greet:
    cmds:
      - echo "Hello ${NAME}, deploying ${VERSION:-latest}"
    env:
      NAME:
        type: string
        required: true
      VERSION:
        type: string
        default: "1.0.0"

Syntax:

• ${VAR} or $VAR — variable value
• ${VAR:-default} — use default if unset
• $$ — literal $

Built-in variables:

• ${MERIADOC_PROJECT_ROOT} — absolute path to the project root
• ${MERIADOC_SPEC_DIR} — directory containing the spec file

Env files

Load variables from .env files:

tasks:
  start:
    cmds:
      - node server.js
    env_files:
      - .env
      - .env.local

Meriadoc also automatically loads .env from the project root if it exists.

Priority (highest to lowest):

1. --env KEY=VALUE flags from the CLI
2. Inline env: defaults in the spec
3. env_files: entries (last file wins)
4. Auto-loaded .env from project root

Working directory

By default, commands run in the directory containing the spec file. Override with workdir (resolved relative to the project root):

tasks:
  frontend:
    workdir: packages/web
    cmds:
      - npm run build

Preconditions

Run checks before the task. If a precondition fails, the task is blocked:

tasks:
  deploy:
    cmds:
      - ./deploy.sh
    preconditions:
      - cmds:
          - test -f .env.prod
        on_failure:
          continue: false
          cmds:
            - echo ".env.prod not found — copy from .env.example"

Set continue: true to log the failure and proceed anyway.

Failure handling

Run cleanup commands when a task fails:

tasks:
  migrate:
    cmds:
      - npm run db:migrate
    on_failure:
      continue: false
      cmds:
        - echo "Migration failed! Check logs."
        - npm run db:rollback

Dry run

Preview a task without executing it:

meriadoc run task deploy --dry-run

Prints resolved env vars, interpolated commands, preconditions, and failure handlers.

Agent annotations

Control how AI agents interact with this task:

tasks:
  deploy-prod:
    description: "Deploy to production"
    agent:
      risk_level: critical        # low | medium | high | critical
      requires_approval: true
      confirmation: "This deploys to production. Are you sure?"
    cmds:
      - ./deploy.sh prod

  internal:
    description: "Not exposed to agents"
    agent:
      enabled: false              # hidden from MCP discovery
    cmds:
      - ./internal.sh

See Agents / MCP for the full picture.