pi-env

Pi extension that sets process environment variables from settings.json at startup.

Declare env vars declaratively in your pi settings instead of using shell wrappers or polluting your global shell environment.

Why?

• Scoped to pi only — variables are set inside the pi process without affecting your terminal session or other tools
• Override existing vars — set pi-specific values that take precedence over what's already in your shell (e.g. route a provider through a different endpoint without changing your global AWS config)
• Declarative and portable — commit project-level env config in .pi/settings.json for your team, keep personal values in global settings

Installation

pi install npm:pi-env

Or from git:

pi install https://github.com/ksjf977/pi-env

Usage

Add an "env" key to your global or project settings:

~/.pi/agent/settings.json (global) or .pi/settings.json (project):

{
  "env": {
    "AWS_ENDPOINT_URL_BEDROCK_RUNTIME": "https://my.corp.proxy/bedrock",
    "AWS_BEARER_TOKEN_BEDROCK": "$MY_CORP_TOKEN",
    "AWS_BEDROCK_FORCE_HTTP1": "1",
    "GOOGLE_CLOUD_PROJECT": "my-project",
    "GOOGLE_CLOUD_LOCATION": "us-central1"
  }
}

Environment variables are set before providers initialize, so they're available when pi makes API requests.

Variable interpolation

Reference pre-existing environment variables using pi's value resolution syntax:

| Syntax | Meaning | |--------|---------| | $ENV_VAR | Value of ENV_VAR from the shell environment | | ${ENV_VAR} | Same, braced form (useful when followed by text) | | $$ | Literal $ character | | literal | Used as-is |

{
  "env": {
    "API_URL": "https://${REGION}.api.example.com/v1",
    "AUTH_TOKEN": "$VAULT_TOKEN",
    "PRICE": "$$9.99"
  }
}

Settings hierarchy

Honors pi's settings merge behavior:

1. Global (~/.pi/agent/settings.json) — base defaults
2. Project (.pi/settings.json) — overrides global per-key

If both define env, the project values override global values for the same keys. Unique keys from both levels are merged.

Features

• Scalar coercion — numbers and booleans are coerced to strings via String()
• Stale cleanup — variables removed from settings are unset on /reload
• /env command — print currently configured env vars in the TUI at any time
• Styled output — shows a summary of applied variables on session start
• Warnings — notifies in the TUI for unresolved variables, non-scalar values, or overridden existing env vars

Why not just export in .zshrc?

Shell exports apply to every process. With pi-env, you can:

• Set AWS_ENDPOINT_URL_BEDROCK_RUNTIME for pi without affecting your AWS CLI
• Override AWS_REGION per-project without changing your shell profile
• Keep provider routing config versioned with the project
• Avoid wrapper functions like pi() { VAR=x command pi "$@"; }

License

MIT