Profile Configuration

A profile is a YAML file that describes your full development environment: which repositories to clone, what to run during install, how to handle environments, and what custom commands are available to the team.

File format

name: "my-team"

repositories:
  - name: "api"
    url: "[email protected]:my-org/api.git"
    path: "~/dev/api"
  - name: "frontend"
    url: "[email protected]:my-org/frontend.git"
    path: "~/dev/frontend"

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

install:
  tasks:
    - type: Print
      message: "All repos cloned. Running global setup..."
    - type: Shell
      cmd: "brew bundle --file=~/Brewfile"

commands:
  - name: "test-all"
    usage: "Run tests across all repos"
    tasks:
      - type: Shell
        cmd: "npm test"
        path: "~/dev/api"
      - type: Shell
        cmd: "npm test"
        path: "~/dev/frontend"

Adding profiles from a URL

raid profile add accepts a git repo URL, a raw file URL, or a local path:

# Shallow-clone a repo and import *.raid.yaml, *.raid.yml, and profile.json files found at the root
raid profile add https://github.com/my-org/raid-profiles

# Download a single profile file directly
raid profile add https://raw.githubusercontent.com/my-org/repo/main/team.raid.yaml

# Register a local file
raid profile add ./team.raid.yaml

Raid auto-detects the argument type. Git URLs (including git@ and .git-suffix URLs) are cloned; HTTP URLs ending with .yaml, .yml, or .json are downloaded directly; ambiguous HTTP URLs are probed with git ls-remote. Downloaded profiles are saved to ~/<name>.raid.yaml before registration.

Top-level fields

Field	Required	Description
`name`	Yes	Unique profile identifier
`repositories`	No	List of repositories to manage
`environments`	No	Named environment configurations
`install`	No	Tasks to run after all repos are cloned
`commands`	No	Custom commands available via `raid <name>`
`task_groups`	No	Reusable task sequences

Repositories

Each repository entry defines a repo to clone and optionally what to run after cloning.

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

Field	Required	Description
`name`	Yes	Used to reference the repo (e.g. `raid install api`)
`url`	Yes	Git remote URL
`path`	Yes	Local clone destination
`install.tasks`	No	Tasks to run after this repo is cloned

If a repository already exists at path, cloning is skipped.

Environments

Environments are defined as a list at the top level of the profile. Each environment has a name, optional variables, and optional tasks to run when it is applied.

environments:
  - name: "local"
    variables:
      - name: "API_HOST"
        value: "localhost"
    tasks:
      - type: Shell
        cmd: "docker-compose up -d db"
  - name: "production"
    variables:
      - name: "API_HOST"
        value: "api.my-org.com"
    tasks:
      - type: Confirm
        message: "Switch to production?"

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
`variables[].name`	string	Yes	Variable name
`variables[].value`	string	Yes	Variable value
`tasks`	list	No	Tasks to run when this environment is applied

Individual repositories can define their own environment configuration in their raid.yaml. These are merged with the profile-level environment when applied. See Environments for details.

Install tasks

install.tasks runs after all repositories have been cloned and their own install tasks have completed. Use this for global setup that depends on all repos being present.

install:
  tasks:
    - type: Shell
      cmd: "./scripts/link-configs.sh"

Field	Type	Required	Description
`tasks`	list	No	Tasks to run after all repos are cloned

Commands

Custom commands are available as raid <name>. They run the defined task sequence.

commands:
  - name: "deploy"
    usage: "Deploy all services"
    tasks:
      - type: Shell
        cmd: "./deploy.sh"
        path: "~/dev/api"
    out:
      stdout: true
      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`
`tasks`	list	Yes	Tasks to run
`out`	object	No	Output configuration
`out.stdout`	bool	No	Show stdout (default: `true` when `out` is omitted)
`out.stderr`	bool	No	Show stderr (default: `true` when `out` is omitted)
`out.file`	string	No	Also write all output to this file (supports `$VAR`)

Arguments passed after the command name are available as RAID_ARG_1, RAID_ARG_2, etc. See Custom Commands for details.

See Task Types for everything a task can do.

Task groups

Task groups are reusable task sequences referenced from commands using a Group task.

task_groups:
  install-deps:
    - type: Shell
      cmd: "npm install"

commands:
  - name: "setup"
    usage: "Install dependencies"
    tasks:
      - type: Group
        ref: "install-deps"

Field	Type	Required	Description
`task_groups`	map	No	Map of group name to task list
`task_groups.<name>`	list	Yes	Task sequence for this group

Groups are invoked with the Group task type:

Field	Type	Required	Description
`ref`	string	Yes	Name of the task group to execute
`parallel`	bool	No	Run all tasks in the group concurrently
`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`

Per-repo configuration (`raid.yaml`)

Repositories can define their own commands and environments by committing a raid.yaml at their root. These are automatically merged into the active profile when it loads.

~/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.tasks`	list	No	Tasks to run after this repo is cloned
`commands`	list	No	Repo-scoped custom commands
`environments`	list	No	Repo-scoped environment variables and tasks

Registering and switching profiles

raid profile add ./my-profile.yaml   # register a profile file
raid profile add ./raid.yaml          # register a repo config as a single-repo profile
raid profile list                     # list all registered profiles
raid my-team                          # switch to the 'my-team' profile
raid profile remove my-team          # remove a profile

Single-repo profiles

For projects that ship only a raid.yaml (no wrapping profile file), point raid profile add straight at the repo config:

raid profile add ./raid.yaml

Raid detects the repo schema and registers it as a single-repo profile named after the raid.yaml's name field. Switch to it with raid profile <name> like any other profile. The commands, environments, and install tasks declared in the raid.yaml become available at the top level.

File format​

Adding profiles from a URL​

Top-level fields​

Repositories​

Environments​

Install tasks​

Commands​

Task groups​

Per-repo configuration (raid.yaml)​

Registering and switching profiles​

Single-repo profiles​