CLI

pin <command> [arguments] [flags]

Run pin <command> --help for the full flag list on any command. A reference is whatever you have: a bare id, a full pinterest.com URL, a user/slug board path, or an @handle.

Read commands

Command	What it does
get <ref>	Show one pin by id or URL (single record)
search <query>	Search Pinterest for pins
related <ref>	Pins related to a given pin
topic <slug>	Pins under an interest slug, e.g. home-decor
trending	The trending interest topics
board show <ref>	One board's metadata (single record)
board pins <ref>	A board's pins
board sections <ref>	A board's sections
user show <name>	One profile's metadata (single record)
user pins <name>	A user's saved pins
user boards <name>	A user's public boards

The pin-grid feeds (get, search, related, topic, trending, board pins, user pins) can return empty from a datacenter or cloud IP. See troubleshooting.

Offline reference tools

Command	What it does
ref id <ref>	Classify any reference into its (kind, id). No network.
ref url <kind> <id>	Build the canonical URL for a (kind, id). No network.

Framework commands

Command	What it does
serve [--addr]	Serve the operations over HTTP as NDJSON
mcp	Run as an MCP server over stdio
completion	Generate a shell completion script
version	Print the version and exit

Under serve, each operation is a route, for example GET /v1/get/<ref> and GET /v1/board/show/<ref>.

Global flags

These are shared by every operation, so they work the same on every command.

Flag	Meaning
-o, --output	Output format: auto, table, markdown, json, jsonl, csv, tsv, url, raw
--fields	Comma-separated columns to keep
--template	Go text/template applied per record
--no-header	Omit the header row in table and csv
-n, --limit	Stop after N records (0 means no limit)
--color	auto, always, or never
--rate	Minimum delay between requests
--retries	Retry attempts on rate limit or 5xx
--timeout	Per-request timeout
--user-agent	Override the request User-Agent
--cache-ttl	How long cached responses stay fresh (default 24h)
--no-cache	Bypass on-disk caches
--refresh	Fetch fresh and rewrite the cache
--db	Tee every record into a store (e.g. out.db, postgres://...)
--profile	Named profile for settings and data
--data-dir	Override the data directory
-q, --quiet	Suppress progress output
-v, --verbose	Increase verbosity (repeatable)

See output formats for what -o, --fields, and --template produce, and configuration for environment variables, profiles, and cache behaviour.