# Pactto CLI

> Command-line access to Pactto rooms for Claude Code, Codex, scripts, and CI. Read transcripts, PDFs, docs, and the canvas, and write results back into the room. Every command prints JSON. Requires the Pro plan.

Package: @pactto/cli (current release 2.2.0, Node.js 20 or newer)
Human page: https://www.pactto.com/cli
Chat-assistant alternative (Claude, ChatGPT): https://www.pactto.com/mcp.md

## Setup

1. Have a Pactto account on Pro: https://live.pactto.com
2. Create an API key at https://live.pactto.com/settings/api-keys. It is shown once. Production keys start with pact_prod_, and the CLI picks the server from that prefix. Scope is read or write; write is needed to change the canvas. Keys can be limited to specific rooms and given an expiry date.
3. Install: `npm install -g @pactto/cli@latest` (the same command updates).
4. Teach the agent the CLI: `pactto instructions >> CLAUDE.md` (or AGENTS.md for Codex). Pick a default room: `pactto use <roomId>`.
5. Log in: `pactto auth login` and paste the key, or ask Claude Code: "Help me set up Pactto CLI with my API key".

## Setup commands

| Command | What it does |
|---|---|
| `npm install -g @pactto/cli` | Install or update. Needs Node 20 or newer. |
| `pactto auth login` | Paste the key you created under Settings, API Keys, Create. |
| `pactto auth whoami` | Who the key belongs to, its scope, and the rooms it can reach. |
| `pactto rooms --pretty` | The rooms this key can see. |
| `pactto use room_abc123` | Default room for the commands that follow. |
| `pactto context` | Current default room and the server in use. |
| `pactto instructions >> CLAUDE.md` | The primer that teaches your agent the CLI. |
| `pactto auth logout` | Remove the key from this machine. |

The CLI has about fifty commands in all, for reading, the canvas, Pactto Docs, tables, media, and comments. Run `pactto --help` for the list, or `pactto instructions` for the full primer.

## Without an agent

A key in the environment works without logging in. Set the room the same way, since there is no default room outside a login:

```
PACTTO_API_KEY=pact_prod_... PACTTO_ROOM=room_abc123 pactto canvas list --type pacttoVideo | jq -r ".shapes[].shapeId"
```

## Limits and errors

- Credits: pactto image and pactto pdf-visual spend one Pactto credit each. Everything else is free. With no balance they return insufficient_credits and nothing is charged.
- Rate limit: 120 requests a minute and 2,000 an hour per key. Past that: rate_limited with retryAfter in seconds. Use the batched --file flags for notes and text.
- plan_limit_exceeded: the account is not on Pro.
- forbidden_scope: a read key tried to write.
- forbidden_room: the key is not allowed in that room.
- invalid_api_key: the key expired or was revoked.

## Example prompts for Claude Code or Codex

- List the main topics discussed in room Brainstorming in the last 5 meetings
- Pull the text from every PDF on the canvas and list the deadlines you find.
- Take the meeting notes doc on the canvas and lay out each section as a sticky note on a new board called Summary
- Organize this room: group the images into one board, the videos into another, and the PDFs into a third, then align and space everything so it reads left to right
- Write a Pactto Doc with today's action items for Demian and Sherif
- Create a Tasks table with Task, Owner, and Status columns and add a row for each open item from the transcript
- Mark every video on the canvas as approved
- Add a comment at 0:42 on the hero cut saying the logo comes in too late
- Upload video-final.mp4 and video-for-instagram.mp4 and cover-image-instagram.png to the room and group them in a board called Round 2
- Check Room A and Room B and explain the main reasons the customer said no