Environment variables reference

Pi uses environment variables in three distinct places: its own process configuration, authentication for a selected provider, and the environment of commands launched by the LLM-callable bash and powershell tools. Scope matters: a variable recognized by one provider is not automatically a Pi-wide setting.

Provider credentials

For Pi's built-in providers, credential order is an explicit CLI --api-key or runtime override, a matching stored auth.json API key or OAuth credential, the configured models.json apiKey (a literal or $ENV reference under that file's contract), then the built-in provider's ambient environment. Extension-defined providers may implement a different contract. Use /login to write the protected credential store instead of putting secrets in project files.

Amazon Bedrock and Google Vertex AI also accept ambient cloud credentials described under provider-specific variables. A custom models.json provider can reference an arbitrary variable with "apiKey": "$COMPANY_AI_TOKEN"; a plain uppercase string is a literal, not an environment lookup. See Add a model provider for that file's exact surface.

Runtime flags

Directories and runtime assets

PI_CODING_AGENT_DIR replaces the old broad home-directory switch; it targets Pi's agent configuration, not the operating-system home directory. Direct SDK calls use the paths passed to their constructors and do not automatically reproduce every CLI precedence rule.

export PI_CODING_AGENT_DIR=/srv/pi/agent
export PI_CODING_AGENT_SESSION_DIR=/srv/pi/sessions
export PI_PACKAGE_DIR=/nix/store/example-pi
pi

Offline, version, and telemetry switches

Use --offline or a supported truthy PI_OFFLINE value. Unset the variable to re-enable network work: some 0.85.0 downstream paths test whether PI_OFFLINE exists, so PI_OFFLINE=0 is unsafe and can behave as offline. PI_SKIP_VERSION_CHECK is narrower than offline mode. Do not rely on undocumented spellings for PI_TELEMETRY.

Terminal and editor behavior

PI_HARDWARE_CURSOR=1 makes the TUI hardware cursor visible. PI_TUI_ESC_TIMEOUT accepts a positive finite number of milliseconds for distinguishing a lone Escape from a split Alt-key sequence; the default is 100 ms when SSH_CONNECTION or SSH_TTY exists and 10 ms otherwise.

Pi auto-detects OSC 8 hyperlinks, an inline image protocol, and truecolor. Pi 0.85.0 exposes these exact advanced overrides:

For PI_HYPERLINKS, 1 force-enables OSC 8 hyperlinks, 0 force-disables them, and auto falls back to automatic detection. An explicit boolean terminal.hyperlinks setting overrides both PI_HYPERLINKS and automatic detection; "auto" supplies no setting override.

For PI_IMAGE_PROTOCOL, kitty selects the Kitty protocol and iterm2 selects the iTerm2 protocol; none force-disables inline images, while auto falls back to automatic detection. An explicit protocol or false in the terminal.images setting overrides both PI_IMAGE_PROTOCOL and automatic detection; "auto" supplies no setting override.

For PI_TRUE_COLOR, 1 force-enables truecolor, 0 force-disables it, and auto falls back to automatic detection. An explicit boolean terminal.trueColor setting overrides both PI_TRUE_COLOR and automatic detection; "auto" supplies no setting override.

Force a capability only when the complete terminal, proxy, and multiplexer path supports it, because unsupported escape sequences can corrupt rendering.

Automatic detection recognizes the Zed integrated terminal as truecolor- and hyperlink-capable, but it does not select an inline image protocol there. Under auto, Zed therefore uses the image text fallback; do not force Kitty or iTerm2 sequences unless the actual terminal path supports them.

For Ctrl+G, the externalEditor setting wins, followed by VISUAL, then EDITOR, then the platform fallback. These variables contain an editor command, not file content.

Cache and sharing

PI_CACHE_RETENTION=long requests extended provider prompt caching where the selected API supports it; other values do not select another documented tier. PI_SHARE_VIEWER_URL replaces the base URL used to build the /share viewer link. Neither variable is a credential.

PI_EXPERIMENTAL

PI_EXPERIMENTAL=1 enables 0.85.0's preferred strict JSON-schema sampling for managed tools where the model/API supports it. The exact comparison is 1; true is not accepted. Experimental behavior may change between releases and does not alter project trust or the selected tool set.

Value rules

Environment variables are strings, but Pi does not treat every non-empty string as true. Use only the values above. Paths may be absolute or expanded by the documented CLI path helpers; provider-specific values can also come from a stored credential's scoped env object, which takes precedence over the ambient process for those supported fields.

Proxy and TLS

Pi 0.85.0 configures an Undici EnvHttpProxyAgent for Pi-managed fetch traffic.

Undici also recognizes lowercase forms and gives them precedence over uppercase forms. The global httpProxy setting fills HTTP_PROXY and HTTPS_PROXY only when they are unset. Provider SDKs such as AWS or Google may own separate transports, so these variables are not a guarantee for every extension or cloud client.

SSL_CERT_FILE is not read or installed by Pi's published 0.85.0 transport. Configure custom certificate trust through the selected Node runtime or provider SDK and verify that route independently; do not assume this baseline variable changes Pi-managed TLS.

Provider-specific variables

Azure OpenAI

Azure OpenAI Responses requires AZURE_OPENAI_API_KEY and either AZURE_OPENAI_BASE_URL or AZURE_OPENAI_RESOURCE_NAME. Optional controls are AZURE_OPENAI_API_VERSION and the comma-separated AZURE_OPENAI_DEPLOYMENT_NAME_MAP. The generic OPENAI_ORG_ID baseline variable is not consumed by the 0.85.0 OpenAI provider.

Amazon Bedrock

Bedrock accepts AWS_BEARER_TOKEN_BEDROCK, AWS_PROFILE, or the standard AWS access-key/role chain, including AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optional AWS_SESSION_TOKEN, ECS credentials, and web identity. Region selection reads AWS_REGION or AWS_DEFAULT_REGION. Proxy deployments can use AWS_ENDPOINT_URL_BEDROCK_RUNTIME; AWS_BEDROCK_SKIP_AUTH=1 and AWS_BEDROCK_FORCE_HTTP1=1 are specialized compatibility switches.

Google Vertex AI

Vertex accepts GOOGLE_CLOUD_API_KEY directly. Application Default Credentials instead require a valid default credential file or GOOGLE_APPLICATION_CREDENTIALS, plus GOOGLE_CLOUD_PROJECT (or GCLOUD_PROJECT) and GOOGLE_CLOUD_LOCATION. GOOGLE_API_KEY and GOOGLE_VERTEX_API_KEY are not aliases for the current Gemini and Vertex variables.

Cloudflare

Cloudflare Workers AI uses CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID; AI Gateway additionally requires CLOUDFLARE_GATEWAY_ID. These exact all-uppercase names replace the baseline's misspelled CLOUDflare_* form.

export HTTPS_PROXY=http://proxy.internal.example:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example
export GOOGLE_CLOUD_PROJECT=example-project
export GOOGLE_CLOUD_LOCATION=us-central1

The old ANTHROPIC_BASE_URL variable is also not a current built-in override. Configure a supported custom endpoint in models.json or a provider implementation rather than relying on an ambient alias.

Process markers and shell-tool metadata

CLI and RPC entry points set AI_AGENT=pi and PI_CODING_AGENT=true. Child processes inherit them, but they are not session identifiers and an SDK embedding does not set them automatically. Published 0.85.0 does not emit the old PI_PARENT_SESSION marker.

Pi can expose the following current session context to commands run by the LLM-callable bash and powershell tools:

Default local Bash and PowerShell operations launch a separate child process for each Tool call and use their respective command syntax. Custom operations instead delegate to their configured backend; that backend owns cancellation, cleanup, and whether any execution state persists. The wrapper first removes inherited values for all five session variables. exposeSessionEnvironment defaults to true, but injection requires an Agent/Extension execution context. exposeSessionEnvironment: false suppresses all five session fields even when that context exists. A standalone or custom invocation without that context does not receive them automatically. When injection occurs, the values are resolved before that shell-tool command, so model or reasoning changes affect the next command. The native powershell Tool is Windows-only. These variables are not injected into user-entered ! or !! commands.

When those conditions are met, a custom shell tool created with createBashTool() or createPowerShellTool() exposes the metadata before spawnHook, so preserve the received process environment when adding fields. Without the context, or with exposure disabled, the hook receives an environment with these session fields removed. The existing Bash form remains:

import { createBashTool } from "@earendil-works/pi-coding-agent";

export const bashTool = createBashTool(process.cwd(), {
  spawnHook: (context) => ({
    ...context,
    env: { ...context.env, CI: "1" },
  }),
});

PowerShell customization uses the same hook contract. When registered and executed through Pi with Agent context and default exposure, it receives the same session fields:

import { createPowerShellTool } from "@earendil-works/pi-coding-agent";

export const powerShellTool = createPowerShellTool(process.cwd(), {
  spawnHook: (context) => ({
    ...context,
    env: { ...context.env, CI: "1" },
  }),
});

Disable exposure explicitly on either factory when commands cross a trust boundary. Pi removes inherited session fields first, preventing stale parent metadata from leaking into the command or hook. This Bash example remains valid; replace the factory with createPowerShellTool() for the equivalent PowerShell policy:

import { createBashTool } from "@earendil-works/pi-coding-agent";

export const isolatedBashTool = createBashTool(process.cwd(), {
  exposeSessionEnvironment: false,
  spawnHook: (context) => context,
});

Pitfalls and security

• Do not put API keys in committed shell files, settings.json, extension source, logs, prompts, or transcripts. Prefer /login, a secret manager, or narrowly scoped process injection; remember that child processes inherit exported values.
• Current names are exact. PI_HOME, PI_LOG_LEVEL, PI_PARENT_SESSION, GOOGLE_API_KEY, GOOGLE_VERTEX_API_KEY, GITHUB_TOKEN, OPENAI_ORG_ID, ANTHROPIC_BASE_URL, and misspelled CLOUDflare_* names are not compatibility aliases in published 0.85.0.
• A stored provider credential and a configured models.json apiKey both take precedence over ambient variables. Log out or update the stored entry, and remove or change the configured key, before expecting a rotated shell key to win.
• PI_EXPERIMENTAL is unrelated to provider authentication and is not a permission or “yolo” switch.
• Do not print complete environment dumps while debugging. Inspect only non-secret markers or individual metadata fields, and treat PI_SESSION_FILE as sensitive local data.

Next

• Configuration reference covers settings.json, trust, resources, tools, and sessions.
• API reference covers public SDK surfaces.
• Add a model provider covers models.json, authentication, and custom adapters.