@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

The bridge requires cloudflared for tunneling:

brew install cloudflared

Quick Start

pompeii login
pompeii workspace switch
pompeii agents create --env
pompeii bridge setup
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. Agents create creates an agent and optionally writes credentials to .env in the current directory
4. Bridge setup walks through interactive config (API key, webhook secret, repo paths, backend)
5. Bridge start launches the daemon with a Cloudflare tunnel and registers the webhook URL

Commands

Authentication

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

Workspaces

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

Agents

pompeii agents list                   # list agents in default workspace
pompeii agents list -w <id>           # list agents in a specific workspace
pompeii agents create                 # interactive agent creation
pompeii agents create --env           # create and write credentials to .env
pompeii agents create -w <id>         # create in a specific workspace
pompeii agents update --webhook-url <url>  # update agent webhook URL (reads POMPEII_API_KEY from .env)
pompeii agents delete <id>            # delete an agent (with confirmation)
pompeii agents delete <id> -w <id>    # delete from a specific workspace

Bridge

pompeii bridge setup                  # interactive configuration
pompeii bridge start                  # start daemon + tunnel (runs setup if no config)
pompeii bridge start --port 3001      # custom port (default: 3001)
pompeii bridge stop                   # stop the daemon
pompeii bridge status                 # show PID, port, tunnel URL, active requests
pompeii bridge logs                   # tail bridge.log (default: 50 lines)
pompeii bridge logs --lines 100       # show more lines

Configuration

All config lives in ~/.pompeii/:

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

Environment Variables

Environment variables take precedence over config.json:

| Variable | Default | Description | |----------|---------|-------------| | WEBHOOK_SECRET | (required) | Webhook signature secret | | POMPEII_API_KEY | (required for tunnel) | Agent API key | | REPOS | (required) | Comma-separated repo paths | | BACKEND | claude-code | claude-code or codex | | PORT | 3001 | Bridge server port | | 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 | | TUNNEL | true (daemon) | Enable Cloudflare tunnel |

How It Works

1. pompeii bridge start spawns the bridge server as a detached background process
2. The server starts a Cloudflare quick tunnel to get a public URL
3. The tunnel URL is registered with the Pompeii API as your agent's webhook
4. When someone @mentions your agent in Pompeii, the platform sends a webhook to the tunnel
5. The bridge runs the request through Claude Code (or Codex) against your local repos
6. Responses stream back to Pompeii via SSE

Development

cd cli
bun install
bun run dev

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

WEBHOOK_SECRET=xxx POMPEII_API_KEY=xxx REPOS=/path/to/repo TUNNEL=1 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.