Collect data

pin writes machine-readable output by default the moment you pipe it, so turning a command into a dataset is mostly a matter of choosing a format and a destination. This guide collects the patterns that come up most.

It assumes the quick start. The metadata commands used below (board show, user show, user boards) return data from any network; the pin-grid feeds (search, board pins, user pins, and the rest) need a residential connection, see troubleshooting.

Pipe one record set into jq

Left to auto, pin prints JSONL into a pipe: one JSON object per line, which jq reads without any flags.

pin user boards pinterestman | jq -r '.name'
pin user boards pinterestman | jq 'select(.followers > 1000) | .name'

Use -o json when a tool wants a single array instead of a stream:

pin user boards pinterestman -o json | jq 'length'

Build a CSV or TSV

Pick the columns you care about, then ask for csv or tsv:

pin user boards pinterestman --fields name,pins,followers -o csv > boards.csv
pin user boards pinterestman --fields name,pins,followers -o tsv > boards.tsv

--no-header drops the header row when a downstream tool expects bare rows.

Tee straight into a database

--db writes every emitted record into a store as a side effect of reading, so a session fills a database with no separate import step. The record's kit:"id" field is the key, so re-running a command updates rows in place rather than duplicating them.

pin user boards pinterestman --db pinterest.db          # a local SQLite file
pin board show pinterestman/ball-is-life --db pinterest.db
pin user boards pinterestman --db 'postgres://localhost/pin'

Because the key is stable, you can layer several commands into one store and query across them afterwards:

pin user show pinterestman --db pinterest.db
pin user boards pinterestman --db pinterest.db
sqlite3 pinterest.db '.tables'

Cap and pace a longer pull

--limit stops after N records. --rate spaces requests out so a longer pull stays polite, and --cache-ttl lets a re-run reuse what you already fetched instead of hitting the site again.

pin user boards pinterestman --limit 100 --rate 1s -o jsonl > boards.jsonl
pin user boards pinterestman --limit 100 --refresh          # ignore the cache, fetch fresh

A withheld pin-grid feed exits 3 (no results) and a rate limit exits 5, so a script can tell "nothing came back" apart from "the site asked me to slow down":

if ! pin search "scandinavian kitchen" -n 50 -o jsonl > pins.jsonl; then
  echo "feed empty or throttled (exit $?)" >&2
fi

Format a quick report

A template turns each record into exactly the line you want, for a changelog entry or a chat message:

pin user boards pinterestman \
  --template '{{.Name}}: {{.Pins}} pins, {{.Followers}} followers'

See output formats for the full contract and the field list for every record type.