CLI Auth

CLI Auth & Board Claim

Paperclip has two separate identity flows for humans on the command line and browser:

Board claim — a one-time bootstrap step that promotes your browser-authenticated user to the owner of a freshly started authenticated instance. It migrates the trusted "local board" placeholder into a real, named human account. CLI auth — the everyday flow that pairs a local paperclipai CLI process with a signed-in board user, so the CLI can call /api endpoints on your behalf without you typing credentials into your shell.

Both flows use a short-lived, server-minted challenge and a browser approval page. Both are designed so the secret material (the board API token, the ownership migration) never leaves the browser or the CLI process that asked for it.

This guide walks through both, shows the approval pages, and explains how to use the resulting tokens with the CLI.

---

When you need each flow

You just installed Paperclip in authenticated deployment mode on a server, and the loopback trust is still active → run Board claim once. You want to run paperclipai commands against that instance from your laptop → run CLI auth (paperclipai auth login). You're using trusted deployment mode (loopback-only local dev) → neither flow is required; the CLI and browser already trust the loopback.

---

Claiming a board from the CLI