skills/pi-agent/references/environment-variables.md
Source: https://pi.dev/docs/latest/environment-variables
Pi uses environment variables three ways: variables that configure the Pi process, a marker Pi sets so child processes know they run inside Pi, and session metadata injected into commands run by the LLM-callable bash tool. Provider API-key variables live in references/providers.md.
The CLI and RPC entry points set PI_CODING_AGENT=true. Child processes inherit it. It is not session-specific and is not set automatically when Pi is embedded through the SDK.
Commands run by the LLM-callable bash tool receive:
| Variable | Description |
|---|---|
PI_SESSION_ID | Current session ID |
PI_SESSION_FILE | Absolute path to the session JSONL file; unset for ephemeral sessions |
PI_PROVIDER | Currently selected model provider |
PI_MODEL | Currently selected model ID |
PI_REASONING_LEVEL | Effective reasoning level: off, minimal, low, medium, high, xhigh, max |
Values resolve when each command starts, so switching models affects the next bash command without restarting. PI_PROVIDER/PI_MODEL identify the selected Pi model, not an upstream model a router picks internally. When asked which model is running, inspect these variables instead of inferring from the system prompt:
printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
These are injected into the LLM-callable bash tool only — not into user-entered ! or !! commands.
Custom bash tools built with createBashTool() expose the same variables by default, injected before spawnHook so hooks see them in ctx.env. Disable with exposeSessionEnvironment: false; Pi then also clears inherited values so nested Pi processes do not leak stale parent-session metadata.
| Variable | Description |
|---|---|
PI_CODING_AGENT_DIR | Override the config directory; default ~/.pi/agent |
PI_CODING_AGENT_SESSION_DIR | Override session storage; overridden by --session-dir |
PI_PACKAGE_DIR | Override the package directory (useful for Nix/Guix store paths) |
PI_OFFLINE | Disable startup network operations: update checks, package updates, install/update telemetry |
PI_SKIP_VERSION_CHECK | Disable the pi.dev latest-version request |
PI_TELEMETRY | Override install/update telemetry and provider attribution headers: 1/true/yes or 0/false/no |
PI_CACHE_RETENTION | Set to long for extended provider prompt caching where supported |
PI_SHARE_VIEWER_URL | Override the base URL used by /share |
PI_HARDWARE_CURSOR | Set to 1 to show the hardware cursor (IME positioning) |
VISUAL, EDITOR | External editor fallback when the externalEditor setting is unset |
HTTP_PROXY, HTTPS_PROXY | Proxy outbound HTTP requests |
Names are derived from the rebrandable app name (package.json piConfig.name), so a fork uses a different prefix — see references/development.md.
Other variables documented elsewhere: PI_EXPERIMENTAL (experimental first-time setup, references/settings.md), PI_TUI_WRITE_LOG (raw ANSI capture, references/tui.md), AWS_BEDROCK_FORCE_CACHE and other cloud variables (references/providers.md), LLAMA_BASE_URL/LLAMA_API_KEY (references/llama-cpp.md).