Custom commands

Run a custom command defined in the active profile or any of its repositories.

raid <command>

Examples

raid deploy
raid migrate
raid test-all

Run raid --help to see all available commands, including any defined in the active profile.

Defining commands

Custom commands are defined in the commands section of your profile or in a repository's raid.yaml.

profile.yaml

commands:
  - name: "deploy"
    usage: "Deploy all services"
    tasks:
      - type: Shell
        cmd: "./deploy.sh"
        path: "~/dev/api"

~/dev/api/raid.yaml

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

Arguments

Custom commands accept positional arguments, which are exposed as RAID_ARG_1, RAID_ARG_2, etc.

raid deploy prod us-east-1

profile.yaml

commands:
  - name: "deploy"
    usage: "Deploy to a target environment and region"
    tasks:
      - type: Print
        message: "Deploying to $RAID_ARG_1 in $RAID_ARG_2"
      - type: Shell
        cmd: "./scripts/deploy.sh $RAID_ARG_1 $RAID_ARG_2"

The variables are set for the duration of the command and cleared afterwards.

Declared arguments and flags

Commands can also declare named positional arguments and flags. Declared values are bound to env vars named after the field's name (uppercased) and made available to tasks for the duration of the command — so name: ticket becomes $TICKET. Required values that aren't supplied cause raid to reject the invocation with a clear cobra error.

profile.yaml

commands:
  - name: "patch"
    usage: "Apply a patch to a SUV host"
    args:
      - name: ticket
        usage: "Ticket number"
        required: true
      - name: comment
        usage: "Optional changelog note"
    flags:
      - name: suv
        short: s
        usage: "Target SUV hostname"
        required: true
      - name: verbose
        short: v
        type: bool
      - name: retries
        type: int
        default: 3
    tasks:
      - type: Print
        message: "Patching $TICKET on $SUV (retries=$RETRIES, verbose=$VERBOSE)"
      - type: Shell
        cmd: ./scripts/patch.sh "$TICKET" --host "$SUV" --retries "$RETRIES"

Invocation:

raid patch --suv host.example.com -v 12345 "rolling out the fix"
raid patch -s host.example.com 67890         # comment optional

Field on args[] / flags[]	Meaning
name	Long form (--name) and the env var (uppercased).
short (flags only)	Single-character short form, e.g. s → -s.
usage	Short description shown in --help.
type (flags only)	string (default), bool, or int. Bool flags bind as the literal strings "true" / "false".
required	When true, cobra rejects the invocation if the value is omitted.
default (flags only)	Used when the flag is omitted. Type must match type.

Once a command declares args, cobra rejects extra positional values beyond the declared list — the cap is len(args). To accept an unbounded number of positional arguments, omit args: and read them from $RAID_ARG_1, $RAID_ARG_2, … as before. RAID_ARG_N remains populated for declared positional values too, so a task can reference either $TICKET (named) or $RAID_ARG_1 interchangeably.

Output configuration

Use the out field to control what output a command shows and optionally write it to a file.

commands:
  - name: "build"
    usage: "Build all services (quiet)"
    out:
      stdout: true            # show stdout (default: true when out is omitted)
      stderr: false           # hide stderr
      file: "~/logs/build.log"  # also write all output to a file (supports $VAR)
    tasks:
      - type: Shell
        cmd: "npm run build"

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

Repo-scoped commands

When a profile and a repository define commands with the same name, the profile's version takes priority for raid <command>. To explicitly target a specific repository's command, use:

raid <repo-name> <command>

For example, if both the profile and the backend repo define a test command:

raid test           # runs the profile-level "test"
raid backend test   # runs the backend repo's "test"

Each repository that defines commands appears as a subcommand in raid --help. Run raid <repo> --help to see that repo's available commands.

Constraints

Custom command names cannot shadow reserved built-in CLI names: profile, install, env, doctor, context, telemetry, help, version, completion.

Running tasks in parallel

Use concurrent: true on adjacent tasks to run them in parallel:

commands:
  - name: "test-all"
    usage: "Run tests across all repos"
    tasks:
      - type: Shell
        cmd: "npm test"
        path: "~/dev/api"
        concurrent: true
      - type: Shell
        cmd: "npm test"
        path: "~/dev/frontend"
        concurrent: true
      - type: Print
        message: "All tests passed"

See Task Types for everything a task can do.