pinboard

pinboard

pinboard keeps a Git mirror of a Pinboard account, answers questions from it, and changes bookmarks through the Pinboard v1 API. Pinboard stays authoritative: the mirror is never written back, so it can lag behind Pinboard but cannot drop anything Pinboard holds.

Run it as pinboard when bin/ is on PATH, otherwise as <skill-dir>/scripts/pinboard.

Setup

• PINBOARD_API_TOKEN: the API token (USER:HEX) from https://pinboard.in/settings/password.
• The mirror is a Git clone at ~/.pinboard (or PINBOARD_REPO, or --repo DIR before the command). Clone the mirror repository there; an empty clone is fine, and the first pinboard sync imports every bookmark and pushes main.
• pinboard doctor checks the token, the clone, the files and freshness without calling the API. It asks origin for its branch head, without fetching, to report commits this clone lacks.
• publicsuffixlist is pinned in the script's PEP 723 header and imported only by domain-tags; other commands do not load it. uv fetches it once, then uses its cache.

Reading

Reads never call the API, so they are as fresh as the last sync; each says when that was (on stderr, or as mirror.synced with --json). They read the clone's last commit, so a sync in progress never shows half done.

pinboard search kotlin coroutines          # every term must match
pinboard search --tag recipes lemon --json # notes truncated; paged by --cursor
pinboard get https://example.com/post      # one bookmark, notes in full
pinboard tags | head                       # tags, most used first
pinboard history https://example.com/post  # the mirror's versions of one URL

search matches each term case-insensitively against the title, notes, tags and URL, newest first, 20 per page; --limit N and the printed --cursor continue. It exits 1 when nothing matches and 2 on an error.

Writing

Writes go to Pinboard first; each bookmark is then read back with posts/get and committed to the mirror, so the next search sees it.