Doctor

Check the active profile and configuration for issues.

raid doctor

What it checks

Doctor inspects the current profile and reports findings at three severity levels:

Level	Meaning
OK	No issues found
WARN	Something looks off but raid can still function
ERROR	A problem that will prevent raid from working correctly

Checks include:

• Active profile exists and is valid YAML
• All repository paths and URLs are present
• Referenced task groups exist
• Environment names are unique
• Custom command names don't shadow built-in commands
• Every verify: entry on the profile and per-repo raid.yaml files

Verify entries

If your profile or any repo's raid.yaml defines a verify: block, doctor runs every entry and surfaces each as its own finding:

Outcome	Severity	What it means
First-try pass	ok	The verify's tasks: exited cleanly on the first try.
Remediated	warn	tasks: failed, the optional onFail: block ran, and the re-run of tasks: then passed. The precondition holds now — but it didn't before, so doctor warns you to investigate why.
Failed	error	Either no onFail: was defined, onFail: itself failed, or the retry of tasks: failed again. The underlying task error is included in the finding's message.

Doctor runs verify tasks with the same execution context as install: — the active environment, raid vars, and task options all apply. A failure on one verify entry does not prevent subsequent entries from running, so you see the full health picture in a single pass.

:::warning Verify tasks execute real work Doctor invokes the actual tasks: and onFail: blocks you've defined — that's any task type raid supports (shell commands, HTTP, Git, Template, Prompt/Confirm, SetVar, …), not just shell. Non-shell tasks can still make network calls, mutate files, or prompt for input. Keep verify checks small, fast, and side-effect-light (a node --version probe, a test -f, a Wait against a local port). Heavy bootstrap work belongs in install:. :::

When to run it

Run raid doctor after:

• Initial setup to verify your profile loaded correctly
• Adding a new repository or environment
• Pulling a teammate's updated profile
• Something isn't working as expected

raid doctor

If everything is configured correctly you'll see all OK entries. Any ERROR entries need to be resolved before the affected features will work.

JSON output

Pass --json to get a structured report — useful in CI checks or agent workflows. The exit code is unchanged: 1 when any finding has severity error, 0 otherwise.

raid doctor --json

{
  "findings": [
    { "severity": "ok", "check": "git", "message": "installed" },
    { "severity": "warn", "check": "repo/api", "message": "not cloned at ~/dev/api", "suggestion": "Run `raid install api`" }
  ],
  "summary": { "ok": 1, "warnings": 1, "errors": 0 }
}

Severity is one of ok, warn, or error. The suggestion field is omitted when empty.