npm package: @pompeii-ai/cli
Description: CLI for [Pompeii](https://pompeii.ai). Manage your account, workspaces, and agents from the terminal. Run a local bridge daemon that connects your dev environment to Pompeii so AI agents can work on your codebase when @mentioned in conversations.
Latest version: 0.12.0

# @pompeii-ai/cli

CLI for [Pompeii](https://pompeii.ai). Manage your account, workspaces, and agents from the terminal. Run a local bridge daemon that connects your dev environment to Pompeii so AI agents can work on your codebase when @mentioned in conversations.

## Install

```bash
npm i -g @pompeii-ai/cli
pnpm add -g @pompeii-ai/cli
yarn global add @pompeii-ai/cli
bun add -g @pompeii-ai/cli
```

To update an existing install:

```bash
pompeii update
```

## Quick Start

```bash
pompeii auth login
pompeii workspace switch
pompeii bridge sync
pompeii bridge start
```

1. **Login** opens your browser to authenticate with your Pompeii account
2. **Workspace switch** sets your default workspace (auto-selected if you only have one)
3. **Bridge sync** pulls a personal bridge agent you already created in the dashboard, rotates its API key, and writes local bridge config
4. **Bridge start** launches the daemon, which connects outbound to Pompeii over WebSocket

## Commands

### Authentication

```
pompeii auth login       # authenticate via browser
pompeii auth logout      # clear stored session
pompeii auth whoami      # show current user, email, and workspaces
```

### Workspaces

```
pompeii workspace list      # list all workspaces (marks default with *)
pompeii workspace switch    # interactively switch default workspace
```

### Bridge

```
pompeii bridge setup                  # interactive configuration
pompeii bridge sync                   # sync dashboard-created personal bridge agents for the current workspace
pompeii bridge start                  # start the bridge daemon
pompeii bridge stop                   # stop the daemon
pompeii bridge restart                # restart the daemon, or start it if stopped
pompeii bridge logs                   # tail bridge.log (default: 50 lines)
pompeii bridge logs --lines 100       # show more lines
```

### Maintenance

```
pompeii update                        # update the CLI and restart any bridges that were running
```

## Configuration

All config lives in `~/.pompeii/`:

| File          | Contents                               |
| ------------- | -------------------------------------- |
| `auth.json`   | OAuth tokens, email, default workspace |
| `config.json` | repos, backend, daemon settings        |
| `.env`        | `POMPEII_API_KEY`                      |
| `daemon.json` | runtime state (PID, start time)        |
| `bridge.log`  | daemon stdout/stderr                   |

### Environment Variables

Environment variables take precedence over `config.json`:

| Variable                | Default                                           | Description                    |
| ----------------------- | ------------------------------------------------- | ------------------------------ |
| `POMPEII_API_KEY`       | (required)                                        | Agent API key                  |
| `REPOS`                 | (required)                                        | Comma-separated repo paths     |
| `BACKEND`               | `claude-code`                                     | `claude-code` or `codex`       |
| `MAX_TURNS`             | `25`                                              | Max agent turns per request    |
| `MAX_CONCURRENT`        | `3`                                               | Max concurrent agent sessions  |
| `ALLOWED_TOOLS`         | Read,Edit,Bash,Glob,Grep,Write,WebSearch,WebFetch | Comma-separated tool allowlist |
| `HEARTBEAT_INTERVAL_MS` | `15000`                                           | Heartbeat interval in ms       |
| `POMPEII_API_URL`       | `https://api.pompeii.ai`                          | API base URL                   |

## How It Works

1. `pompeii bridge start` spawns the bridge daemon as a detached background process
2. The daemon connects outbound to Pompeii over WebSocket
3. When someone @mentions your agent in Pompeii, the platform dispatches the request over that WebSocket connection
4. The bridge runs the request through Claude Code (or Codex) against your local repos
5. Responses stream back to Pompeii over the same connection

## Development

```bash
cd cli
bun install
bun run dev
```

For local dev without the daemon, set env vars directly:

```bash
POMPEII_API_KEY=xxx REPOS=/path/to/repo bun run dev
```

## Publishing

Publishing is automated via CI. Push a tag matching `cli-v*`:

```bash
git tag cli-v0.2.0
git push origin cli-v0.2.0
```

The `prepublishOnly` script runs `tsc` automatically before publish.