npm package: @pocketbk/cli
Description: Pocketbook AI Gateway — universal LLM proxy for Claude Code, Cursor, Aider, OpenClaw and any CLI tool
Author: Brian Godfrey
Latest version: 2.0.1

# @pocketbook/cli

Universal LLM proxy for Claude Code, Cursor, Aider, and any AI coding tool. Route all your team's AI calls through the Pocketbook gateway for cost governance, model optimization, and usage visibility — with no code changes required.

## How it works

Pocketbook sits between your AI tools and the LLM providers. It intercepts every call, routes it to the best model for the task, enforces your org's budget rules, and logs everything to your dashboard.

```
Claude Code → Pocketbook proxy → Pocketbook gateway → gpt-4o-mini / claude-sonnet / etc.
```

Your tools don't know anything changed. You get full visibility and control.

---

## Prerequisites

- Node.js 18 or later
- An invite from your organization's Pocketbook admin

---

## Install

```bash
npm install -g @pocketbook/cli
```

---

## Quick start (2 minutes)

**1. Log in**
```bash
pocketbook login
```

You'll receive a one-time code at your work email. Enter it when prompted.

**2. Start the proxy**
```bash
pocketbook start --detach
```

**3. Route your tools**
```bash
# bash / zsh
eval $(pocketbook env)

# PowerShell
pocketbook env --shell powershell | Invoke-Expression
```

That's it. All supported tools now route through your organization's gateway.

---

## Supported tools

| Tool | Env vars set |
|------|-------------|
| Claude Code | `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY` |
| Cursor | `OPENAI_API_BASE`, `OPENAI_API_KEY` |
| Aider | `ANTHROPIC_BASE_URL`, `OPENAI_API_BASE` |
| Continue.dev | `ANTHROPIC_BASE_URL`, `OPENAI_API_BASE` |
| OpenClaw | `ANTHROPIC_BASE_URL` |
| LiteLLM | All of the above |
| OpenAI CLI | `OPENAI_API_BASE`, `OPENAI_BASE_URL` |

---

## Commands

```bash
pocketbook login               # Authenticate with your work email (OTP)
pocketbook logout              # Sign out
pocketbook whoami              # Show current user

pocketbook start               # Start proxy (foreground)
pocketbook start --detach      # Start proxy (background)
pocketbook start --port 3101   # Custom port
pocketbook stop                # Stop background proxy

pocketbook status              # Recent calls: model, provider, cost, latency
pocketbook status --watch      # Live view, refreshes every 2s

pocketbook env                 # Print export commands (all tools)
pocketbook env --tool claude-code        # Specific tool
pocketbook env --shell powershell        # PowerShell format
pocketbook env --unset                   # Remove env vars

pocketbook tools               # List supported tools
pocketbook config              # View config
```

---

## Per-project cost tracking

Create a `.pocketbook` file in any project root:

```json
{ "label": "my-project-name" }
```

Calls from that directory are attributed to that label in your org's dashboard.

---

## Make env vars permanent

Add to your shell profile so tools are always routed:

```bash
# ~/.zshrc or ~/.bashrc
eval $(pocketbook env)
```

```powershell
# PowerShell $PROFILE
pocketbook env --shell powershell | Invoke-Expression
```

---

## Troubleshooting

**"Not authenticated" error** — Run `pocketbook login` and try again.

**Claude Code showing a login prompt** — Run `eval $(pocketbook env)` in the same terminal before launching Claude Code. If prompted, select option 2 (Anthropic Console account).

**"Port already in use"** — Run `pocketbook start --port 3101`, then re-run `eval $(pocketbook env)`.

**No account found** — Ask your admin to invite you from the Pocketbook dashboard under Settings → Users.

---

## Uninstall

```bash
pocketbook env --unset
pocketbook stop
npm uninstall -g @pocketbook/cli
```

---

## About

Pocketbook AI Gateway gives engineering teams visibility and control over AI API spend. Learn more at [pocketbk.com](https://pocketbk.com).