Create a dops Runbook

Directory Structure

Runbooks live under DOPS_HOME/catalogs/<catalog>/<runbook-name>/:

~/.dops/catalogs/<catalog>/<runbook-name>/
├── runbook.yaml    # Runbook definition
└── script.sh       # Automation script (POSIX sh)

runbook.yaml Schema

name: <runbook-name>          # Must match directory name
version: 1.0.0
description: Short description of what this runbook does
risk_level: low               # low | medium | high | critical
script: script.sh
parameters:
  - name: endpoint
    type: string              # See parameter types below
    required: true
    description: What this parameter does
    scope: global             # local | global | catalog | runbook
    default: ""               # Optional default value
    secret: false             # If true, masked in UI, excluded from MCP
    options: []               # Required for select and multi_select

Parameter Types

Risk Levels

Scopes

Values are saved to the encrypted vault.json (age AEAD, tamper-resistant).

Script Template (POSIX sh)

#!/bin/sh
set -eu

# dops passes parameters as UPPERCASE environment variables.
# Parameter "endpoint" → $ENDPOINT
# Parameter "dry_run" → $DRY_RUN
ENDPOINT="${ENDPOINT:?endpoint is required}"
DRY_RUN="${DRY_RUN:-false}"

main() {
  echo "==> Stage 1/2: Validate"
  echo "    Checking ${ENDPOINT}..."
  # TODO: implement

  echo ""
  echo "==> Stage 2/2: Execute"
  echo "    Running operation..."
  # TODO: implement

  echo ""
  echo "✓ Done"
}

main "$@"

Shell Style Rules (POSIX-compatible)

1. Use #!/bin/sh — not #!/bin/bash (POSIX compatibility for Linux/macOS)
2. Use set -eu — not set -euo pipefail (pipefail is not POSIX)
3. Quote all variables: "${var}" not $var
4. Use [ ] not [[ ]] — POSIX test
5. Use $(command) not backticks
6. Stderr for errors: echo "error" >&2
7. Indent with 2 spaces, no tabs
8. Put main() at the bottom of the script
9. Use command -v not which
10. Use printf over echo -e for portability

Output Conventions

# Stage headers
echo "==> Stage 1/3: Build"

# Indented details
echo "    Compiling source..."

# Success
echo "✓ Build complete"

# Failure
echo "✗ Build failed" >&2

# Summary block
echo "========================================="
echo "  Summary"
echo "========================================="
echo "  Status: SUCCESS"
echo "========================================="

Workflow

1. Determine the catalog name and runbook name
2. Create the directory: mkdir -p ~/.dops/catalogs/<catalog>/<name>
3. Write runbook.yaml with the schema above
4. Write script.sh following the POSIX template
5. chmod +x script.sh
6. If the catalog is new, register it: dops catalog add ~/.dops/catalogs/<catalog>
7. Test: launch dops, navigate to the runbook, execute it