# pi-dotenv

Load `~/.pi/agent/.env` into `process.env` at pi startup.

## Install

```bash
pi install npm:pi-dotenv
```

Or install from a local path:

```bash
pi install /path/to/pi-dotenv
```

## Usage

Create `~/.pi/agent/.env`:

```dotenv
TAVILY_API_KEY=tvly-...
AGENTMAIL_API_KEY=...
XYZ_API_KEY=fake_123
```

Restart pi. Existing shell env vars are never overwritten.

## Load order

pi-dotenv loads the file when pi loads the extension. An extension that reads
`process.env` when pi loads it (not in an event handler) sees these values only
if pi-dotenv loads first. Put `npm:pi-dotenv` first in `packages` in
`~/.pi/agent/settings.json`. Extensions from `pi -e`, `.pi/extensions/`,
`~/.pi/agent/extensions/`, and project packages always load before global
packages. Extensions that read `process.env` in `session_start` or later are
not affected.

## How it works

- Loads the dotenv file at extension load (factory time), so extensions that read
  `process.env` while pi loads are already served; reloads on each `session_start`
  (idempotent, picks up edits across `/new`, `/resume`, `/fork`)
- Uses `@dotenvx/dotenvx` with `processEnv: {}` (no ambient variable interpolation)
- Never overrides an env var already set in the shell
- Synchronous, minimal, zero network calls