` | Set the initial interactive theme for this run without changing settings |\n| `--verbose` | Force verbose startup |\n| `-a`, `--approve` | Trust project-local files for this run |\n| `-na`, `--no-approve` | Ignore project-local files for this run |\n| `-h`, `--help` | Show help |\n| `-v`, `--version` | Show version |\n\n### File Arguments\n\nPrefix files with `@` to include in the message:\n\n```bash\npi @prompt.md \"Answer this\"\npi -p @screenshot.png \"What's in this image?\"\npi @code.ts @test.ts \"Review these files\"\n```\n\n### Examples\n\n```bash\n# Interactive with initial prompt\npi \"List all .ts files in src/\"\n\n# Non-interactive\npi -p \"Summarize this codebase\"\n\n# Non-interactive with piped stdin\ncat README.md | pi -p \"Summarize this text\"\n\n# Named one-shot session\npi --name \"release audit\" -p \"Audit this repository\"\n\n# Different model\npi --provider openai --model gpt-4o \"Help me refactor\"\n\n# Model with provider prefix (no --provider needed)\npi --model openai/gpt-4o \"Help me refactor\"\n\n# Model with thinking level shorthand\npi --model sonnet:high \"Solve this complex problem\"\n\n# Limit model cycling\npi --models \"claude-*,gpt-4o\"\n\n# Read-only mode\npi --tools read,grep,find,ls -p \"Review the code\"\n\n# Disable one extension or built-in tool while keeping the rest available\npi --exclude-tools ask_question\n\n# High thinking level\npi --thinking high \"Solve this complex problem\"\n```\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `AI_AGENT` | Set to `pi` by the CLI and RPC entry points so generic tooling can attribute child processes to Pi |\n| `PI_CODING_AGENT` | Set to `true` by the CLI and RPC entry points so child processes can detect that they run inside Pi |\n| `PI_CODING_AGENT_DIR` | Override config directory (default: `~/.pi/agent`) |\n| `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory (overridden by `--session-dir`) |\n| `PI_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) |\n| `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |\n| `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request |\n| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers. Use `1`/`true`/`yes` to enable or `0`/`false`/`no` to disable. This does not disable update checks |\n| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |\n| `PI_RULES_DISABLED` | Disable the built-in rules extension when set to `1`, `true`, `yes`, or `on` (case-insensitive) |\n| `PI_RULES_MAX_RULE_CHARS` | Set the positive-integer character cap for each formatted rule payload (default: `12000`) |\n| `PI_RULES_MAX_RESULT_CHARS` | Set the positive-integer character cap for each complete static or dynamic rules block (default: `40000`) |\n| `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |\n\nRules limits are resolved when the built-in extension is registered. Empty,\nzero, negative, fractional, partially numeric, scientific, hexadecimal,\nsigned, non-ASCII-digit, and unsafe-integer values preserve the documented\ndefaults.\n\nCommands run by the LLM-callable bash tool also receive current session metadata:\n\n| Variable | Description |\n|----------|-------------|\n| `PI_SESSION_ID` | Current session ID |\n| `PI_SESSION_FILE` | Absolute session JSONL path; unset for ephemeral sessions |\n| `PI_SESSION_CWD` | Current session working directory |\n| `PI_GOAL_STORE_FILE` | Absolute session goal-store path, including in-memory sessions; the file need not exist yet |\n| `PI_PROVIDER` | Currently selected model provider |\n| `PI_MODEL` | Currently selected model ID |\n| `PI_REASONING_LEVEL` | Current effective reasoning level |\n\nThese values are resolved when each command starts, including terminal-extension PTY bash. Eval kernels snapshot them at kernel start and pass them to their children. See [Environment Variables](docs/environment-variables.md#shell-tool-session-environment) for semantics, examples, and custom-tool opt-out.\n\n---\n\n## Contributing & Development\n\nSee [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines and [docs/development.md](docs/development.md) for setup, forking, and debugging.\n\n## License\n\nMIT\n\n## See Also\n\n- [@earendil-works/pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai): Core LLM toolkit\n- [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core): Agent framework\n- [@earendil-works/pi-tui](https://www.npmjs.com/package/@earendil-works/pi-tui): Terminal UI components\n\n\n pi.dev domain graciously donated by\n
\n ![\"Exy](\"docs/images/exy.png\")
exe.dev\n
\n","readmeFilename":"README.md"}![\"pi](\"https://pi.dev/logo-auto.svg\"){kind=logo}
\n \n![\"Discord\"](\"https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white\"){kind=icon}
![\"npm\"](\"https://img.shields.io/npm/v/@earendil-works/pi-coding-agent?style=flat-square\")
![\"Interactive](\"docs/images/interactive-mode.png\")
![\"Tree](\"docs/images/tree-view.png\")
![\"Doom](\"docs/images/doom-extension.png\")