# Quickstart

> Install, authenticate with API key or /login, start interactive pi, and confirm the default read/write/edit/bash tool surface.

- 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/README.md`
- `packages/coding-agent/package.json`
- `packages/coding-agent/examples/sdk/01-minimal.ts`
- `packages/coding-agent/src/cli/auth-command.ts`
- `packages/coding-agent/src/core/auth-storage.ts`

---

---
title: "Quickstart"
description: "Install, authenticate with API key or /login, start interactive pi, and confirm the default read/write/edit/bash tool surface."
---

`@earendil-works/pi-coding-agent` ships the `pi` binary (`dist/cli.js`) and exposes a coding agent CLI whose package description is a session-managed surface with `read`, `bash`, `edit`, and `write` tools. Interactive use is the default entry: install the package, authenticate with an environment API key or interactive `/login`, run `pi`, then talk to the model against that four-tool default.

## Prerequisites

| Requirement | Value |
|-------------|--------|
| Package | `@earendil-works/pi-coding-agent` |
| Node.js | `>=22.19.0` (`engines.node`) |
| CLI bin | `pi` → `dist/cli.js` |
| Config directory name | `piConfig.configDir` = `.pi` |

Pi is a minimal terminal coding harness that runs in four modes (interactive, print/JSON, RPC, SDK). This page covers the interactive path only.

## Install

<Tabs>
  <Tab title="npm">
    ```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.
  </Tab>
  <Tab title="Installer">
    ```bash
    curl -fsSL https://pi.dev/install.sh | sh
    ```
  </Tab>
</Tabs>

### Verify the binary

After install, `pi` must resolve on your `PATH`. The published package wires:

```json
"bin": {
  "pi": "dist/cli.js"
}
```

## Authenticate

Authenticate with either a provider API key in the environment or a subscription via interactive `/login`. Both paths feed the same provider/model selection surface (`/model` or Ctrl+L after a successful login).

### Option A: API key (environment)

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

API-key authentication is BYOK: set the provider’s key in the environment, then start `pi`. The README documents many API-key providers (Anthropic, OpenAI, Azure OpenAI, Google Gemini, xAI, OpenRouter, and others). Use the key that matches the provider you intend to select.

### Option B: Subscription (`/login`)

```bash
pi
/login  # Then select provider
```

Documented subscription targets include:

- Anthropic Claude Pro/Max
- OpenAI ChatGPT Plus/Pro (Codex)
- GitHub Copilot

Also available interactively: `/logout` for credential management, and `/login llama.cpp` for the llama.cpp router server (then `/llama` for model load/unload, `/model` to select).

### Credential storage (what `/login` writes)

Credentials are stored in `auth.json` under the agent directory (default path construction: `join(getAgentDir(), "auth.json")`).

| Property | Behavior |
|----------|----------|
| File mode | Written with mode `0o600` |
| Parent directory | Created with mode `0o700` when missing |
| Empty bootstrap | Missing file is created as `{}` before locked writes |
| Concurrency | File-locked reads/writes via `proper-lockfile` |

Supported credential shapes in `auth.json` (per provider id):

| `type` | Required fields |
|--------|-----------------|
| `api_key` | Optional `key` (string) and/or `env` (object of string values) |
| `oauth` | `access` (string), `refresh` (string), `expires` (finite number) |

Invalid shapes throw (`Invalid auth.json: expected an object`, or `Invalid auth.json credential for provider "<id>"`). Missing file loads as empty credentials for read-only storage (`ENOENT` → `{}`).

### Optional: non-interactive auth CLI

For scripts and checks (not required for first interactive use):

```text
pi auth print-api-key [--provider <provider>] [--model <model>]
pi auth print-bearer-token [--provider <provider>] [--model <model>] [--min-expiry <duration>]
pi auth check [--provider <provider>] [--model <model>] [--json] [--credentials] [--no-refresh]
```

| Rule | Detail |
|------|--------|
| Scope | Auth commands require at least one of `--provider` or `--model` |
| Flags accepted | Only `--provider` and `--model` (plus the subcommand-specific flags above) |
| OAuth refresh | `auth check` refreshes expired OAuth credentials by default; `--no-refresh` disables that |
| `--min-expiry` | Only for `print-bearer-token`; duration like `30m` or `1h` |
| `--json` / `--credentials` / `--no-refresh` | Only for `auth check` |

Unknown auth subcommands fail with:

```text
Unknown auth command "...". Use "pi auth print-api-key", "pi auth print-bearer-token", or "pi auth check".
```

## Start interactive pi

```bash
pi
```

Then talk to pi in the editor. The interactive layout is:

| Region | Contents |
|--------|----------|
| Startup header | Shortcuts (`/hotkeys` for all), loaded AGENTS.md files, prompt templates, skills, extensions |
| Messages | User messages, assistant responses, tool calls/results, notifications, errors, extension UI |
| Editor | Input area; border color indicates thinking level |
| Footer | Working directory, session name, token/cache usage, cost, context usage, current model |

### Useful first commands

Type `/` in the editor to open commands:

| Command | Purpose |
|---------|---------|
| `/login`, `/logout` | Manage provider credentials |
| `/model` | Switch models (also Ctrl+L) |
| `/settings` | Thinking level, theme, message delivery, transport |
| `/session` | Session info (file, ID, messages, tokens, cost) |
| `/new` | Start a new session |
| `/resume` | Pick from previous sessions |

Editor affordances for day-one use:

| Feature | How |
|---------|-----|
| File reference | Type `@` to fuzzy-search project files |
| Path completion | Tab |
| Multi-line | Shift+Enter (Ctrl+Enter on Windows Terminal) |
| Bash passthrough | `!command` runs and sends output to the model; `!!command` runs without sending |

## Confirm the default tool surface

By default, pi gives the model four tools:

| Tool | Role |
|------|------|
| `read` | Read project content |
| `write` | Create/overwrite files |
| `edit` | Edit existing files |
| `bash` | Run shell commands |

This matches the package description: *“Coding agent CLI with read, bash, edit, write tools and session management.”*

Verification signals in interactive mode:

1. After a prompt that needs workspace access, tool calls appear in the **Messages** region.
2. Footer totals include usage reported by tools (not only assistant text).
3. No extra built-in tools ship by default (features like subagents and plan mode are intentionally skipped; add them via skills, prompt templates, extensions, or pi packages).

### After auth: pick a model

Configured provider catalogs refresh automatically. Force a refresh with:

```bash
pi update --models
```

Then select any tool-capable model from an authenticated provider with `/model` (or Ctrl+L).

## Minimal programmatic path (optional)

If you embed instead of using the TUI, the package main export exposes `createAgentSession`. Defaults discover skills, extensions, tools, and context files from `cwd` and `~/.pi/agent`; the model comes from settings or the first available:

```ts
import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();

try {
	session.subscribe((event) => {
		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
			process.stdout.write(event.assistantMessageEvent.delta);
		}
	});

	await session.prompt("What files are in the current directory?");
	session.state.messages.forEach((msg) => {
		console.log(msg);
	});
} finally {
	session.dispose();
}
```

Package public surface used here:

| Export | Path |
|--------|------|
| Main | `@earendil-works/pi-coding-agent` → `./dist/index.js` |
| RPC entry | `@earendil-works/pi-coding-agent/rpc-entry` |
| Client | `@earendil-works/pi-coding-agent/client` |

## Quick failure checks

| Symptom | Check |
|---------|--------|
| Install scripts blocked | Expected when using `--ignore-scripts`; not required for normal npm installs |
| No model / no auth | Set an API key env var or run `/login` and select a provider |
| `auth check` / print credential errors | Pass `--provider` and/or `--model`; avoid unrelated flags |
| Invalid credentials file | Repair `auth.json` shape (`api_key` or `oauth` fields above); invalid objects throw on load |
| Auth file lock contention | Concurrent writers use file locks; compromise of the lock surfaces as `Auth storage lock was compromised` |
| Node too old | Use Node `>=22.19.0` |

## End-to-end checklist

<Steps>
  <Step title="Install">
    ```bash
    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
    ```
    Confirm `pi` is on `PATH`.
  </Step>
  <Step title="Authenticate">
    Either export a provider API key (for example `ANTHROPIC_API_KEY`) or start `pi` and run `/login`.
  </Step>
  <Step title="Start interactive mode">
    ```bash
    pi
    ```
    Confirm startup header, editor, and footer render.
  </Step>
  <Step title="Select model">
    Use `/model` (or Ctrl+L) on an authenticated provider.
  </Step>
  <Step title="Confirm tools">
    Prompt the agent to inspect the working directory or edit a file. Expect tool activity under the default `read` / `write` / `edit` / `bash` surface only.
  </Step>
</Steps>

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    npm and installer paths, bin entry, package exports, and verification for `@earendil-works/pi-coding-agent`.
  </Card>
  <Card title="Authentication" href="/authentication">
    API keys, OAuth login, credential storage, auth checks, and refresh behavior.
  </Card>
  <Card title="Tools and allowlists" href="/tools">
    Default `read`/`write`/`edit`/`bash` tools, extension tools, and allowlist filters.
  </Card>
  <Card title="Run modes" href="/run-modes">
    Interactive, print/JSON, RPC, and SDK modes and when to choose each.
  </Card>
  <Card title="Providers and models" href="/providers-and-models">
    Built-in providers, model catalogs, refresh, and selection.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Binary flags, auth subcommands, and package bin wiring.
  </Card>
  <Card title="SDK" href="/sdk">
    Embed with `createAgentSession` and the main package export.
  </Card>
  <Card title="Overview" href="/overview">
    What pi is, the four run modes, and first docs routes.
  </Card>
</CardGroup>