Environment variables

PiG reads these variables at startup. Each one has a setting or a default that covers the normal case, so set a variable only when you need to change PiG from outside its configuration: in a container, in CI, or while debugging.

Variables named PI_* are read for compatibility with Pi 1.5.0 (Pi's environment variable reference). Directory variables use the spellings selected by PIG_USE_PI_DIRS; other paired variables accept both spellings. Provider credential variables, such as ANTHROPIC_API_KEY, are listed in Providers and in pig --help.

Location

In default mode, PIG_HOME moves settings, keybindings, sessions, trust decisions and installed packages together. In shared mode it moves only PiG-owned product state. See Using Pi's directories.

Worked example: try PiG without touching your own setup

To test a change or follow a guide on a clean footing, point PiG at an empty folder. pig diagnose prints where PiG will read and write, so run it first. Checked on PiG:

PIG_HOME=/tmp/scratch pig diagnose | grep -E "config root|agent dir|auth.json"

config root:       /tmp/scratch
agent dir:         /tmp/scratch/agent
auth.json:         /tmp/scratch/agent/auth.json
  (no auth.json: run `pig login`)

Everything PiG now stores (settings, sessions, credentials, installed Packages) goes below /tmp/scratch, and ~/.pig is not read or written. You sign in again inside the scratch home. Delete the folder to start over.

PIG_CODING_AGENT_DIR moves only the agent directory and wins over PIG_HOME for it:

PIG_HOME=/tmp/scratch PIG_CODING_AGENT_DIR=/tmp/elsewhere pig diagnose | grep -E "config root|agent dir|auth.json"

config root:       /tmp/scratch
agent dir:         /tmp/elsewhere
auth.json:         /tmp/elsewhere/auth.json
  (no auth.json: run `pig login`)

With only XDG_CONFIG_HOME=/tmp/xdg set, the root is /tmp/xdg/pig (agent dir: /tmp/xdg/pig/agent).

One mistake to avoid: a shell that already has PIG_CODING_AGENT_DIR set keeps using that directory even when you set PIG_HOME. If pig diagnose shows an agent directory you did not expect, run env | grep -E "^PI" and unset what you find.

Network

Set PIG_OFFLINE in CI. Without it, every run checks for updates and fails slowly when the network is blocked.

Offline mode, from --offline, PIG_OFFLINE or PI_OFFLINE, sets PI_OFFLINE=1 and PI_SKIP_VERSION_CHECK=1 in the environment extensions inherit, as Pi does. Pi extensions that check PI_OFFLINE see PiG's offline mode.

Version output

Use this opt-in when a Pi-compatible launcher checks the version before it starts PiG. The output is the version of the Pi build PiG ports, not a fabricated release.

Diagnostics

Set PIG_DEBUG=1 and PIG_DEBUG_KEYS=1 when a keybinding does not respond. The log shows whether the key reaches PiG and uses the active keybinding manager. Diagnostic logging preserves user overrides. See terminal setup.

Use PI_TUI_DEBUG_REDRAW=1 when the view jumps while output arrives. The log records each full repaint's cause in pi-tui-debug.log in the configured TUI log directory, normally the agent directory. Standalone TUI instances without a configured log directory do not write redraw logs. Pi reads the same variable. PiG ignores the names PIG_DEBUG_REDRAW and PI_DEBUG_REDRAW.

When a session ends without you asking it to, look in the agent directory (~/.pig/agent, or $PIG_HOME/agent, or the directory PIG_CODING_AGENT_DIR names). exit.log has one line for each signal (SIGHUP, SIGTERM, SIGINT), each closed terminal, each extension shutdown() and each failed interactive run, with the time, the pid and the parent pid. If only the input closes while the terminal stays open, PiG keeps running, as Pi does. crashes.json has the panics and fatal errors, and the next start announces the newest one. A session that the operating system killed leaves no line of its own, so the next start adds one to exit.log. pig diagnose prints these paths and the newest exit.log lines. exit.log and crash-output/ are PiG additions (D102). The PIG_DEBUG log is pig-debug.log in the temporary directory ($TMPDIR on macOS, a per-user folder).

PIG_DEBUG_TOOLS and PI_TUI_DEBUG_REDRAW need the exact value 1. The other diagnostic variables accept any non-empty value.

Go runtime

Sessions

Shell tool session environment

Commands that the bash and powershell tools run receive the current session state, as in Pi:

PiG resolves the values when each command starts, so a model or thinking change applies to the next command. PiG removes inherited values of these variables first, so a nested pig does not see its parent's session. User ! and !! commands do not receive them.

Experimental features

Updates and deployments

These variables describe how PiG was installed, so pig update can give the right instruction. A product deployment sets them. You do not need them for a normal install.

Display

Each has a setting that does the same thing. A terminal.hyperlinks, terminal.images or terminal.trueColor setting wins over its variable. See settings.

VISUAL, then EDITOR, name the external editor when the externalEditor setting is unset.

Extensions and piglets

The PIG_SDK_* variables point a build at an SDK checkout instead of the staged copy. Use them while developing the SDK itself. See extensions.

Process markers

PiG sets two markers that every child process inherits, as Pi does. PiG names itself in AI_AGENT where Pi names itself (D26):

Related

• Providers lists the credential variables for each provider.
• Settings lists the configuration files and keys, which cover the same behavior.
• Terminal setup covers display and key problems.