Skip to content
pin

Quick start

Fetch your first record with pin.

Once pin is on your PATH, look up a board. A reference is whatever you have: a bare id, a full pinterest.com URL, a user/slug board path, or an @handle.

pin board show pinterestman/ball-is-life

By default you get an aligned table. Ask for JSON when you want to pipe it:

$ pin board show pinterestman/ball-is-life -o json
[
  {
    "id": "...",
    "name": "ball is life",
    "slug": "ball-is-life",
    "url": "https://www.pinterest.com/pinterestman/ball-is-life/",
    "owner": "pinterestman",
    "pins": 0,
    "followers": 0
  }
]

Profiles work the same way, by username or @handle:

pin user show pinterestman
pin user boards pinterestman --limit 5 --fields name,pins,followers

Shape the output

The same flags work on every command:

pin user show pinterestman --fields username,followers,boards
pin board show pinterestman/ball-is-life --template '{{.Name}} ({{.Followers}})'
pin user boards pinterestman -o jsonl | jq .name

-o takes auto, table, json, jsonl, csv, tsv, url, or raw. Left to auto, it prints a table to a terminal and JSONL into a pipe, so the same command reads well by hand and parses cleanly downstream. See output formats for the full contract.

Resolve a reference offline

The ref commands classify and build references with no network call:

pin ref id https://www.pinterest.com/pin/123456/ -o json   # -> {kind: pin, id: 123456}
pin ref url user alice                                       # the canonical profile URL

Serve it instead

The same operations are available over HTTP and to agents over MCP:

pin serve --addr :7777 &
curl -s 'localhost:7777/v1/board/show/pinterestman/ball-is-life'   # NDJSON
pin mcp                                                            # MCP over stdio

A note on empty feeds

The metadata commands above (board show, user show, user boards) return data from any network. The pin-grid feeds (search, related, topic, trending, board pins, user pins, get) can come back empty from a datacenter or cloud IP because of Pinterest's anti-bot measures. When a feed is withheld, pin exits with no results (exit 3) rather than fabricating. See troubleshooting.

2 min read