Schema Reference

Complete field reference for profile files and repository raid.yaml files.

Published JSON Schemas

Raid publishes versioned JSON Schemas under a stable URL. Point your editor or agent at these to get autocomplete, validation, and inline docs:

File	Schema URL
*.raid.yaml profile files	https://raidcli.dev/schema/v1/raid-profile.schema.json
Per-repo raid.yaml files	https://raidcli.dev/schema/v1/raid-repo.schema.json
Shared $defs (referenced by the two above)	https://raidcli.dev/schema/v1/raid-defs.schema.json

The /v1/ path is a stability contract — schemas under it are kept backwards-compatible. Breaking changes will publish to /v2/.

Add a # yaml-language-server modeline to wire schema validation in your editor:

# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json
name: my-project

Editors that consult SchemaStore (VS Code + Red Hat YAML, JetBrains, Neovim with yaml-language-server, Helix, …) auto-associate *.raid.yaml and raid.yaml with the published schemas, so the modeline is optional.

---

Profile file

name: "my-team"

repositories:
  - ...

environments:
  - ...

install:
  tasks:
    - ...

commands:
  - ...

task_groups:
  group-name:
    - ...

Top-level fields

Field	Type	Required	Description
name	string	Yes	Unique profile identifier
repositories	list	No	Repositories to clone and manage
environments	list	No	Named environment configurations
install	object	No	Install configuration
commands	list	No	Custom commands available via raid <name>
task_groups	map	No	Reusable named task sequences
verify	list	No	Declarative preconditions surfaced by raid doctor

---

Repository

repositories:
  - name: "api"
    url: "[email protected]:my-org/api.git"
    path: "~/dev/api"
    install:
      tasks:
        - type: Shell
          cmd: "npm install"

Field	Type	Required	Description
name	string	Yes	Used to reference the repo (e.g. raid install api)
url	string	No	Git remote URL. Omit for local-only directories with no git remote — raid skips cloning and runs install tasks against the existing path.
path	string	Yes	Local clone destination (supports ~). For local-only repos, the path must already exist.
install	object	No	Install configuration for this repo

---

Environment

environments:
  - name: "local"
    variables:
      - name: "LOG_LEVEL"
        value: "debug"
    tasks:
      - type: Shell
        cmd: "docker-compose up -d db"

Field	Type	Required	Description
name	string	Yes	Environment name used with raid env <name>
variables	list	No	Variables to set when the environment is applied
tasks	list	No	Tasks to run when this environment is applied

Variables

Each entry in the variables list is an object with a name and value:

variables:
  - name: "LOG_LEVEL"
    value: "debug"

Field	Type	Required	Description
name	string	Yes	Variable name
value	string	Yes	Variable value

---

Command

commands:
  - name: "deploy"
    usage: "Deploy all services"
    tasks:
      - type: Shell
        cmd: "./deploy.sh"
    out:
      stdout: true
      stderr: false
      file: "~/logs/deploy.log"

Field	Type	Required	Description
name	string	Yes	Command name — invoked as raid <name>
usage	string	No	Description shown in raid --help
args	list	No	Declared positional arguments. See Args.
flags	list	No	Declared flags / options. See Flags.
tasks	list	Yes	Task sequence to run
options	object	No	Shared options block. Same shape as on tasks. Fires once per command — independent of per-task options.
agent	object	No	MCP-facing safety hint. Absence equates to {safe: false}.
out	object	No	Output configuration

Command names cannot shadow built-in names: install, env, profile, doctor.

Arguments passed after the command name are available as RAID_ARG_1, RAID_ARG_2, etc. Declared args and flags (below) additionally bind to env vars named after each entry's name (uppercased).

Command args

Each entry under args declares a positional argument. The supplied value is exported as an env var named after name (uppercased) for the duration of the command.

Field	Type	Required	Description
name	string	Yes	Argument name — uppercased to form the env var.
usage	string	No	Short description shown in --help.
required	bool	No	If true, the command fails when the positional value is omitted. Defaults to false.

Command flags

Each entry under flags declares a long-form --name flag (and optionally a -x short form). Values bind to an env var named after name (uppercased).

Field	Type	Required	Description
name	string	Yes	Flag name — long form is --name, env var is NAME.
short	string (1 char)	No	Single-character short form, e.g. v → -v.
usage	string	No	Short description shown in --help.
type	enum	No	One of string (default), bool, int. Bool flags bind as the literal strings "true" / "false".
required	bool	No	If true, cobra rejects the invocation when the flag is omitted.
default	string | bool | int	No	Value used when the flag is omitted. Must match type.

Agent metadata

Optional agent: block on a command surfaces safety hints to MCP clients (the raid context serve agent toolkit). Clients read the resolved form from the raid://workspace/commands resource and use it to decide whether to auto-execute a command or prompt the user for approval.

Default unsafe: a command without an agent: block surfaces to MCP clients as {safe: false}. Existing config keeps its current "requires confirmation" semantics; opt commands in by setting safe: true.

Hint only: raid does not gate execution on these fields. The agent client implements the policy.

commands:
  - name: test
    usage: "Run unit tests"
    tasks:
      - type: Shell
        cmd: "go test ./..."
    agent:
      safe: true
      reads:  ["./..."]
      writes: []
      description: "Run the Go unit-test suite. Idempotent, no side effects."

  - name: deploy
    usage: "Deploy to production"
    tasks:
      - type: Shell
        cmd: "./scripts/deploy.sh"
    agent:
      safe: false
      description: "Deploys live infrastructure. Requires user confirmation."

Field	Type	Required	Description
safe	bool	No	When true, the command is idempotent and free of side effects — MCP clients that respect the hint may auto-execute it. Defaults to false.
reads	list<string>	No	Paths or globs the command reads. Informational only — raid does not parse or enforce these.
writes	list<string>	No	Paths or globs the command writes. Informational only.
description	string	No	Agent-facing description. Overrides usage in the MCP workspace resource when set.

Output

When out is omitted, both stdout and stderr are shown. When out is present, only streams explicitly set to true are displayed. The file field writes all output to the specified path regardless of the stdout/stderr settings.

Field	Type	Required	Description
stdout	bool	No	Show stdout (default: true when out is omitted)
stderr	bool	No	Show stderr (default: true when out is omitted)
file	string	No	Also write all output to this file (supports $VAR)

---

Install

install:
  tasks:
    - type: Shell
      cmd: "npm install"

Field	Type	Required	Description
tasks	list	No	Task sequence to run

---

Verify

Declarative precondition checks. Each entry runs tasks: to assert that a dependency or environmental requirement is in place. An optional onFail: remediation gets exactly one chance to fix things — if remediation succeeds, raid re-runs tasks: once; if that pass succeeds the verify is reported as remediated, otherwise it fails.

Verify entries are accepted on both profiles and per-repo raid.yaml files. They share execution context with install: — the active environment, raid vars, and task options all apply. raid doctor runs every verify entry and surfaces each as a finding: a first-try pass is an ok finding, a successful self-heal is a warn (the precondition holds now, but didn't before — worth knowing), and a failure is an error carrying the underlying task error.

verify:
  - name: "Node installed"
    tasks:
      - type: Shell
        cmd: "node --version"
    onFail:
      - type: Shell
        cmd: "nvm install --lts"

Field	Type	Required	Description
name	string	Yes	Human-readable label for the precondition. Surfaced in doctor output and structured errors.
tasks	list	Yes	Task sequence asserting the precondition. A non-zero exit anywhere in the sequence marks the verify as failed.
onFail	list	No	Remediation task sequence. Runs once when tasks: fails; if it succeeds, tasks: is re-run a single time.

Keep verify checks small and fast — they're meant to be run frequently as part of health diagnostics. Heavy bootstrap work belongs in install:.

---

Task groups

task_groups:
  install-deps:
    - type: Shell
      cmd: "npm install"
  health-check:
    - type: Wait
      url: "http://localhost:3000/health"
      timeout: "30s"

Field	Type	Required	Description
task_groups	map	No	Map of group name to task list

Task groups are referenced using the Group task type.

---

Task

All tasks share these common fields:

Field	Type	Required	Description
type	string	Yes	Task type (case-sensitive, Title Case)
name	string	No	Human-readable label, surfaced in logs and agent output. Does not affect execution.
concurrent	bool	No	Run in parallel with adjacent concurrent tasks. Concurrent task output is line-prefixed with the task name on TTY sinks so interleaved output stays attributable — see Output prefixing in concurrent runs.
condition	object	No	Conditions that must all pass for the task to run
options	object	No	Shared options block. Composes across every task type and is also accepted on commands.

Options

The options: block is shared by every task type and by user-defined commands. Omitting it (or any field within) leaves default behavior unchanged. New fields ship additively.

Field	Type	Default	Description
showExeTime	bool	false	When true, raid prints a dim line to stderr after the task (or command) completes: <name> complete in 1.2s. Fires for both success and failure. On a command this fires once for the whole command's elapsed time; on a task it fires for that single task. The two are independent — set both to time the command end-to-end and see per-task breakdowns.
continueOnFailure	bool	false	When true, a non-zero exit from this task does not abort the parent command — subsequent tasks still run and a dim warning is logged to stderr (warning: <name> failed (continueOnFailure): <err>). The command's overall exit code is only affected by non-ignored failures, so this lets you opt into best-effort steps (cleanup teardown, lint/format probes, optional checks) without losing the ability to detect strict failures elsewhere. Only meaningful on tasks; no effect when set on a command's own options.

commands:
  - name: build
    options:
      showExeTime: true     # one final line after the whole command
    tasks:
      - type: Shell
        name: server-build
        cmd: swift build
        options:
          showExeTime: true # per-task line too
      - type: Shell
        name: client-install
        cmd: npm install
        options:
          showExeTime: true

Output:

server-build complete in 164.1s
client-install complete in 0.9s
build complete in 165.0s

continueOnFailure makes a task best-effort — its non-zero exit logs a warning but doesn't abort the command:

commands:
  - name: ci
    tasks:
      - type: Shell
        name: lint
        cmd: golangci-lint run
        options:
          continueOnFailure: true   # don't fail CI on lint findings
      - type: Shell
        name: test
        cmd: go test ./...          # real failures still abort
      - type: Shell
        name: cleanup-cache
        cmd: rm -rf .cache
        options:
          continueOnFailure: true   # cleanup is best-effort

If golangci-lint reports findings, raid prints warning: lint failed (continueOnFailure): … to stderr but still runs go test. A failing test then aborts the command with the usual error path.

Condition

Field	Type	Description
platform	string enum	darwin, linux, or windows
exists	string	Only run if this file or directory exists
cmd	string	Only run if this command exits 0

All specified condition fields must be satisfied for the task to run.

Task types

Shell | Script | HTTP | Wait | Template | Group | Git | Prompt | Confirm | Set | Print

---

Shell

Run a shell command.

Field	Type	Required	Description
type	string	Yes	"Shell"
cmd	string	Yes	Command to execute
shell	string enum	No	Shell to use: bash, sh, zsh, powershell, pwsh, ps, cmd. Default: bash
literal	bool	No	Skip $VAR expansion before passing to the shell. Default: false
path	string	No	Working directory. Defaults to ~ for profile tasks, the repo directory for repo tasks

Script

Run a script file.

Field	Type	Required	Description
type	string	Yes	"Script"
path	string	Yes	Path to the script file
runner	string enum	No	Interpreter: bash, sh, zsh, python, python2, python3, node, powershell

If runner is omitted, the script is executed directly (requires a shebang line or executable permission).

HTTP

Download a file from a URL.

Field	Type	Required	Description
type	string	Yes	"HTTP"
url	string	Yes	URL to download from
dest	string	Yes	Local path to write the file to

Wait

Poll a URL or TCP endpoint until it responds, or until the timeout is reached.

Field	Type	Required	Description
type	string	Yes	"Wait"
url	string	Yes	HTTP(S) URL or TCP host:port to poll
timeout	string	No	Max wait duration (e.g. 30s, 1m). Default: 30s

Template

Render a template file with variable substitution and write it to a destination.

Field	Type	Required	Description
type	string	Yes	"Template"
src	string	Yes	Path to the template file. Supports $VAR and ${VAR} substitution
dest	string	Yes	Path to write the rendered file to

Group

Execute a named task group defined in the profile's task_groups section.

Field	Type	Required	Description
type	string	Yes	"Group"
ref	string	Yes	Name of the task group to execute
parallel	bool	No	Run all tasks in the group concurrently. Default: false
attempts	int	No	Retry the group on failure up to this many times
delay	string	No	Wait between retry attempts (e.g. 1s, 500ms). Default: 1s

Git

Perform a git operation on a repository.

Field	Type	Required	Description
type	string	Yes	"Git"
op	string enum	Yes	Git operation: pull, checkout, fetch, reset
branch	string	No	Target branch (required for checkout, optional for others)
path	string	No	Path to the git repository. Defaults to the current working directory

Prompt

Prompt the user for input and store the result in a variable.

Field	Type	Required	Description
type	string	Yes	"Prompt"
var	string	Yes	Environment variable name to set with the user's input
message	string	No	Message to display to the user
default	string	No	Default value if the user provides no input

In headless mode (-y, --headless, or RAID_HEADLESS=1), Prompt skips stdin and uses default: directly. A Prompt without a default: fails with HEADLESS_PROMPT_NO_DEFAULT — add a default for every Prompt you expect CI / agent invocations to run.

Confirm

Ask the user for yes/no confirmation. If the user answers no, remaining tasks are skipped.

Field	Type	Required	Description
type	string	Yes	"Confirm"
message	string	No	Confirmation prompt to display

In headless mode, Confirm auto-accepts. Express destructive-action gates through a verify: entry, a condition: on the destructive task, or an explicit env-var check — anything that doesn't depend on a user answering a prompt.

Set

Set an environment variable for the duration of the command session.

Field	Type	Required	Description
type	string	Yes	"Set"
var	string	Yes	Environment variable name to set
value	string	Yes	Value to assign. Supports $VAR and ${VAR} substitution

Print

Print a message to the terminal.

Field	Type	Required	Description
type	string	Yes	"Print"
message	string	Yes	Message to print. Supports $VAR substitution unless literal is true
color	string enum	No	Terminal color: red, green, yellow, blue, cyan, white
literal	bool	No	Skip environment variable expansion in the message. Default: false

---

Repository raid.yaml

A repository can define its own install tasks, commands, and environments by committing a raid.yaml at its root. These are merged into the active profile at load time.

~/dev/api/raid.yaml

name: "api"
branch: "main"

install:
  tasks:
    - type: Shell
      cmd: "npm install"

commands:
  - name: "migrate"
    usage: "Run database migrations"
    tasks:
      - type: Shell
        cmd: "go run ./cmd/migrate"

environments:
  - name: "local"
    variables:
      - name: "DATABASE_URL"
        value: "postgres://localhost:5432/api_dev"
  - name: "staging"
    variables:
      - name: "DATABASE_URL"
        value: "postgres://staging-db.internal:5432/api"

Field	Type	Required	Description
name	string	Yes	Must match the repository name in the profile
branch	string	Yes	Default branch to checkout on clone
install	object	No	Install configuration for this repo
commands	list	No	Repo-scoped custom commands
environments	list	No	Repo-scoped environment variables and tasks
verify	list	No	Declarative preconditions surfaced by raid doctor