[env] — environment variables

Declare the env vars your rig needs. rig install collects them; rig doctor checks them.

[env]
required = ["FINANCIAL_DATASETS_API_KEY"]
optional = ["OPENAI_API_KEY"]
template = "scripts/.env.example"
target   = ".env"

Fields

`required` (list of strings)

Env vars the rig cannot function without. rig install prompts for each (unless --env / --env-file provides them); rig doctor reports missing ones as required gaps.

`optional` (list of strings)

Env vars the rig will use if present, but can run without. Reported by rig doctor as non-required checks.

`template` (string, file path)

Path to an example env file shipped with the rig. Typically .env.example or scripts/.env.example. If present, rig install shows it to the user (or the agent) as a starting point, and rig doctor includes it in the remediation hint for missing vars.

`target` (string, file path)

Path the values get written to during rig install. Defaults to .env at the workspace root. Use a different value if the rig reads env from a non-default location.

Lookup order

When rig doctor checks whether a var is "set", it looks (in order):

The file at target (default .env).
process.env of the rig CLI invocation.

Either counts as set. Values in process.env take precedence at runtime, because the rig's runtime tooling (e.g. Claude Code) reads process.env not target unless you wire it up.

`rig install` flow

For each var in required not already set:

If --env KEY=value was passed, use that.
Else if --env-file <path> was passed and the var is in it, use that.
Else if running interactively, prompt the user (with a hint from template).
Else leave it missing and report it in the install summary.

Values get written to target as KEY=value lines. Existing lines for the same key are replaced; other lines untouched.

Example: a typical research rig

[env]
required = [
  "FINANCIAL_DATASETS_API_KEY",
  "ALPHAVANTAGE_API_KEY"
]
optional = [
  "OPENAI_API_KEY",
  "ANTHROPIC_API_KEY"
]
template = "scripts/.env.example"
target   = ".env"

Then scripts/.env.example:

# Required
FINANCIAL_DATASETS_API_KEY=
ALPHAVANTAGE_API_KEY=

# Optional
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=

What rig won't do

Never ship real env values inside the artifact. .env and .env.* are in the default excludes.
Never read or write env vars on other machines.
Never persist values to ~/.config/rig/ (that's auth, not setup).