Use a rig
Run setup
rig install — the convergent setup step that creates dirs, fills env vars, merges permissions, and (for shared rigs) starts the sync daemon.
rig installRun this in a rig workspace after rig use (or in
your own workspace after rig init). It's safe to re-run — every action is
idempotent and convergent.
What it does
| Step | Source | Side effect |
|---|---|---|
| Create declared folders | [local].dirs | Creates dirs with .rigkeep placeholders if empty. |
| Collect env vars | [env] | Asks for each required var, writes to [env].target (default .env). Skipped if --env/--env-file provided. |
| Merge Claude permissions | [permissions] | Union-merges into .claude/settings.json. Deny rules always win. |
| Run install hooks | [install].commands | Only with --run-hooks or interactive confirmation. |
| Cache observed state | — | Writes .rig/setup.json (latest rig doctor snapshot). |
| Start sync daemon | [sync], if enabled | Spawns tapd if this is a shared rig. |
What it never does:
- Install MCP servers, language runtimes, or plugins.
- Modify files outside the workspace.
- Read or write
~/.config/rig/config.json(that's auth, not setup).
Flags
| Flag | What |
|---|---|
--yes | Accept all non-destructive defaults; don't prompt. |
--interactive | Force interactive prompts even in non-TTY. |
--run-hooks | Run [install].commands shell hooks. Default: skip them. |
--env KEY=value | Provide an env var non-interactively. Repeatable. |
--env-file <path> | Read env vars from a file (KEY=value lines). |
--json | Emit a machine-readable summary. |
--plain | Plain output for scripts. |
Examples
Set up with prompts:
rig installNon-interactive with env values from a file:
rig install --yes --env-file ./secrets.envIn CI, with hooks:
rig install --yes --run-hooks --env FOO=bar --env BAZ=quxWhat you still need to do yourself
- MCP servers. Rig declares which servers the rig needs via
[mcp]; installing the underlying CLIs (e.g.uvx,npx) and any subordinate dependencies is on you.rig doctorshows what's missing. - Tools.
[tools]lists CLIs the rig expects onPATH.rig doctorflags missing ones with install hints. - Plugins. Claude Code plugin install is still manual; rig records what plugins were detected so you (or an agent) can install them.
rig doctor will surface each of these as a gap with a remediation hint —
see Troubleshoot.
Re-running
rig install is idempotent. Run it again after fixing something and the gap
list should shrink. The agent skill at .claude/skills/rig/SKILL.md
teaches Claude Code to do this loop on your behalf.