@pompeii-ai/cli

CLI for Pompeii. 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

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:

pompeii update

Quick Start

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

cd cli
bun install
bun run dev

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

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

Publishing

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

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

The prepublishOnly script runs tsc automatically before publish.