# Installation

> npm and installer install paths, bin entry, package exports, and verification for @earendil-works/pi-coding-agent.

- Repository: earendil-works/pi
- GitHub: https://github.com/earendil-works/pi
- Human docs: https://grok-wiki.com/public/docs/earendil-works-pi-7860a70e44d1
- Complete Markdown: https://grok-wiki.com/public/docs/earendil-works-pi-7860a70e44d1/llms-full.txt

## Source Files

- `packages/coding-agent/package.json`
- `packages/coding-agent/README.md`
- `packages/coding-agent/CHANGELOG.md`
- `packages/coding-agent/src/cli/args.ts`

---

---
title: "Installation"
description: "npm and installer install paths, bin entry, package exports, and verification for @earendil-works/pi-coding-agent."
---

`@earendil-works/pi-coding-agent` publishes the `pi` CLI (`bin.pi` → `dist/cli.js`) and embeddable ESM exports for SDK, RPC, and client use. Current package version in tree is **0.84.1**. Runtime requirement: **Node.js `>=22.19.0`**.

## Prerequisites

| Requirement | Value |
|-------------|--------|
| Package name | `@earendil-works/pi-coding-agent` |
| Node engine | `>=22.19.0` |
| Module type | ESM (`"type": "module"`) |
| Config directory name | `piConfig.configDir` = `.pi` |
| License | MIT |

Provider credentials are **not** required to install the package. Authentication (API keys or `/login`) is required to run agent turns against a model.

## Install paths

### npm global CLI

```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

`--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.

### Installer script

```bash
curl -fsSL https://pi.dev/install.sh | sh
```

### Project / library dependency

For embedding (SDK / RPC / client), add the package as a dependency and import from the published export map (see [Package surface](#package-surface)):

```bash
npm install @earendil-works/pi-coding-agent
```

Use a package manager and lockfile of your choice; the published identity and export paths are the same.

<Note>
CLI subcommand `pi install <source>` installs **extension sources** into settings. It does not install the `@earendil-works/pi-coding-agent` npm package.
</Note>

## Package surface

### Identity and bin

| Field | Value |
|-------|--------|
| `name` | `@earendil-works/pi-coding-agent` |
| `version` | `0.84.1` |
| `description` | Coding agent CLI with read, bash, edit, write tools and session management |
| `bin.pi` | `dist/cli.js` |
| `main` | `./dist/index.js` |
| `types` | `./dist/index.d.ts` |
| `piConfig.configDir` | `.pi` |

Build marks `dist/cli.js` and `dist/rpc-entry.js` executable (`chmod +x` in the package `build` script).

### Export map

| Export | Import path | Resolves to |
|--------|-------------|-------------|
| Main / SDK | `@earendil-works/pi-coding-agent` | `./dist/index.js` (+ `./dist/index.d.ts`) |
| RPC entry | `@earendil-works/pi-coding-agent/rpc-entry` | `./dist/rpc-entry.js` |
| Client | `@earendil-works/pi-coding-agent/client` | `./dist/client/index.js` (+ types) |

### Published package files

npm publishes: `dist`, `docs`, `examples`, `containerization.md`, `CHANGELOG.md`, `npm-shrinkwrap.json`.

### Related monorepo dependencies

Runtime dependencies (same major line `^0.84.1`):

- `@earendil-works/pi-agent-core`
- `@earendil-works/pi-ai`
- `@earendil-works/pi-client`
- `@earendil-works/pi-protocol`
- `@earendil-works/pi-tui`

Optional: `@mariozechner/clipboard@0.3.9`.

## Verification

<Steps>
  <Step title="Confirm the binary">
    After a global or installer install, the `pi` command should resolve on `PATH` (wired from package `bin.pi` → `dist/cli.js`).
  </Step>
  <Step title="Check version and help">
    ```bash
    pi --version
    # or
    pi -v

    pi --help
    # or
    pi -h
    ```
    Help identifies the app as an AI coding assistant with **read**, **bash**, **edit**, and **write** tools.
  </Step>
  <Step title="Optional auth readiness">
    From 0.84.1: `pi auth check` verifies provider/model credentials and can optionally emit the resolved credential.
  </Step>
  <Step title="First interactive run">
    API key example (Anthropic shown in README; other providers use their own env vars):

    ```bash
    export ANTHROPIC_API_KEY=sk-ant-...
    pi
    ```

    Or start `pi` and authenticate with a subscription:

    ```bash
    pi
    /login   # then select provider
    ```
  </Step>
</Steps>

Default model tools after a successful start: `read`, `write`, `edit`, `bash`.

## Post-install layout (defaults)

| Path / surface | Role |
|----------------|------|
| `~/.pi/agent/sessions/` | Session JSONL storage (auto-save; organized by working context) |
| `~/.pi/agent/models.json` | Custom providers/models (supported API shapes) |
| `~/.pi/agent/keybindings.json` | Custom keybindings |
| `piConfig.configDir` = `.pi` | Package-declared config directory name |

## Update after install

CLI help lists:

```text
pi update [source|self|pi]   Update pi, extensions, or model catalogs
```

Also:

| Command | Purpose |
|---------|---------|
| `pi list` | List installed extensions from settings |
| `pi config [-l]` | TUI to enable/disable package resources (Tab switches scope) |
| `pi auth <command>` | Print credentials or check provider readiness |
| `pi <command> --help` | Help for install/remove/uninstall/update/list/config/auth |

Provider model catalogs can refresh automatically; force with `pi update --models`.

## Standalone binary build (package scripts)

The package defines `build:binary`, which compiles a Bun standalone binary to `dist/pi` using:

```bash
bun build --compile --no-compile-autoload-bunfig ...
```

Changelog 0.84.1: standalone Bun binaries no longer crash on startup when the cwd contains a `bunfig.toml` with `preload`, because compile uses `--no-compile-autoload-bunfig`. This is a **package build** concern, not a separate public install recipe beyond the npm and `install.sh` paths above.

## Run modes after install

Pi runs in four modes (post-install choice, not separate packages):

| Mode | Typical entry |
|------|----------------|
| Interactive TUI | `pi` |
| Print / JSON | `pi --print` / `-p`, `--mode text\|json` |
| RPC | `--mode rpc` or package export `./rpc-entry` |
| SDK | import package main export |

Default CLI provider name in help text: `google` (`--provider <name>`).

## Troubleshooting install and first start

| Symptom | Evidence-backed note |
|---------|----------------------|
| Engine too old | Package requires Node `>=22.19.0` |
| Lifecycle script policy | Prefer `npm install -g --ignore-scripts`; install scripts are not required for normal installs |
| Wrong `pi install` usage | That subcommand manages extension **sources** in settings, not npm package install |
| Auth before first useful turn | Set a provider API key env var, or use `/login`; use `pi auth check` for readiness |
| Bun standalone + `bunfig.toml` preload | Fixed in 0.84.1 via `--no-compile-autoload-bunfig` on binary compile |

Platform notes referenced in the package README (not expanded in this evidence set): Windows, Termux (Android), tmux, terminal setup, shell aliases under package `docs/`.

## Next

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    Install, authenticate, start interactive `pi`, confirm default tools.
  </Card>
  <Card title="Authentication" href="/authentication">
    API keys, OAuth `/login`, credential storage, and auth checks.
  </Card>
  <Card title="Package exports" href="/package-exports">
    Full public export map: main, rpc-entry, client, bin, `piConfig`.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Flags, subcommands, and bin wiring for the `pi` binary.
  </Card>
  <Card title="SDK" href="/sdk">
    Embed via the package main export and control hooks.
  </Card>
  <Card title="Run modes" href="/run-modes">
    Interactive, print/JSON, RPC, and SDK invocation paths.
  </Card>
</CardGroup>