raid

The root raid command. All other commands are subcommands of raid.

raid [command] [flags]

Global flags

These flags can be used with any subcommand.

Flag	Description
-c, --config <path>	Path to the config file (default: ~/.raid/config.toml)
-h, --help	Show help for any command
-v, --version	Print the current raid version
--json	Emit JSON output / errors for scriptable and agent consumption (where supported)
-y, --yes, --headless	Auto-resolve interactive prompts. See Headless mode below
--no-prefix	Disable per-task output prefixing in concurrent runs. See Output prefixing below

Config file

Raid stores its configuration at ~/.raid/config.toml by default. This file tracks which profile is active and where profile files are located.

Use --config to point to a different config file:

raid --config ~/alt-config.toml install
raid -c /tmp/test-config.toml doctor

This is useful when managing multiple independent setups or during testing.

Headless mode

For CI runs, scheduled jobs, and agent-driven invocations there's no human at a terminal to answer interactive prompts. Pass -y, --yes, or --headless (all equivalent) to auto-resolve every prompt:

raid -y deploy
raid --headless install
RAID_HEADLESS=1 raid deploy        # env-var equivalent (same effect)

Behavior:

Task type	Headless behavior
Confirm	Auto-accepts. The prompt is skipped and the next task runs.
Prompt with a default:	Uses the declared default; stdin is not read.
Prompt without a default:	Fails fast with HEADLESS_PROMPT_NO_DEFAULT (exit code 3, category task).

The third row is deliberate: silently setting the variable to an empty string would surface as a confusing downstream failure. Add a default: to every Prompt you expect to run headlessly.

Destructive Confirms in headless mode. Headless auto-accepts every Confirm, so the prompt is no longer a safety gate. Express stronger guardrails 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.

Env var. Set RAID_HEADLESS=1 (or true / yes / on, case-insensitive) for the same effect as the flag. The flag and env var are interchangeable; the flag works by setting the env var so a single read site in lib (lib.IsHeadless()) serves both.

Output prefixing in concurrent runs

When raid runs tasks with concurrent: true, their stdout/stderr lines are prefixed with [task-name] and rendered in a deterministic per-task color, so interleaved output stays attributable:

[build] tsc compiling…
[test] PASS  src/foo.test.ts
[build] tsc finished in 1.4s
[test] PASS  src/bar.test.ts

The task name comes from the name: field; tasks without a name fall back to their type (Shell, Script, Git). Colors are picked from a 6-color palette via a stable hash of the task label, so the same name always gets the same color across runs.

Suppressed on non-TTY sinks. When raid's stdout isn't an interactive terminal — pipes, file redirects, CI logs, the MCP server's capture buffer — prefixing and color are both disabled. raid <cmd> > log.txt and raid <cmd> | grep … produce byte-identical output to today.

Sequential tasks are unprefixed. Tasks without concurrent: true run one at a time in declared order, so their output is already unambiguous; prefixing them would just add visual noise.

Disable on demand. Three escape hatches:

Toggle	What it disables
--no-prefix / RAID_NO_PREFIX=1	Both the prefix and the color. Useful when you want the raw subprocess output even on a TTY.
NO_COLOR=1 (any non-empty value)	Strips ANSI color codes but keeps the prefix. Follows the no-color.org convention.
concurrent: false	The task runs sequentially with the rest, so its output is naturally attributable by ordering.

Trailing partial lines are flushed. When a concurrent task exits without a final newline, raid emits the buffered partial line with its prefix so the last output is still attributed.

Built-in commands

Command	Description
install	Clone repositories and run install tasks
env	Apply, list, or check environments
profile	Create, add, list, switch, or remove profiles
doctor	Check the active configuration for issues
context	Print workspace snapshot; context serve runs the MCP server
telemetry	Manage anonymous CLI telemetry (off by default; on / off / status / purge / preview)
completion	Generate shell autocompletion scripts

Custom commands defined in the active profile or its repositories are also available as raid <name>. See Custom Commands for details.

Version check

Raid checks for updates on every invocation. For informational commands (--help, --version, completion), it waits up to 1.5 seconds for the check to complete. For all other commands, the check runs in the background and does not delay execution.

If an update is available, a notice is printed to stderr:

Raid v0.5.0 (Update available: v0.5.0 → v0.6.0)

Shell completion

Generate autocompletion scripts for your shell:

# Bash
raid completion bash > /etc/bash_completion.d/raid

# Zsh
raid completion zsh > "${fpath[1]}/_raid"

# Fish
raid completion fish > ~/.config/fish/completions/raid.fish

# PowerShell
raid completion powershell > raid.ps1

Run raid completion <shell> --help for detailed instructions for each shell.

Reserved command names

The following names are reserved for built-in commands and cannot be used as custom command names:

profile, install, env, doctor, context, telemetry, help, version, completion

If a custom command in your profile uses a reserved name, it is ignored and a warning is printed.