PNBACKUP(1)

💾 PNBACKUP(1) 💾

okay so bestie, welcome to pinboard-notes-backup — yes that's the real name, the man page header just calls it PNBACKUP(1) because man pages are allergic to fun 💅. anyway. this is the whole thing, every flag, every caveat, no notes skipped. let's go 🫶

---

✨ NAME ✨

pinboard-notes-backup — back up all those notes you've been saving to Pinboard, like the digital packrat icon you are 🎀

---

🌸 SYNOPSIS 🌸

pnbackup [-v | --verbose] -t <username>:<api token> <output file>

---

💖 OPTIONS 💖

the mandatory besties (must always be given, no skipping 🙈)

• -t <username>:<api token> — your Pinboard username, then a colon, then your Pinboard API token. literally that exact format. you can find both of these on the Pinboard password settings page (https://pinboard.in/settings/password). go get 'em 🔑
• <output file> — the name of the SQLite database file where your notes are gonna live. if this file doesn't exist yet, it gets created for you, no cap ✨

the optional slay (available when you want them)

• -v, --verbose — shows you more info about how the sync is going. perfect for when you need to watch the progress bar like it's a season finale 😭
• -h, --help — displays the usage information and dips. iconic exit behavior 👑
• --version — displays the version number and dips. also iconic 🌈

---

🦋 DESCRIPTION 🦋

okay so here's the vibe: this program does one-way synchronization between Pinboard and a local database. one way. that means it updates your local file to match what's on the server — and it will never make any changes on the server. your notes on Pinboard are safe, she's not touching them, periodt 💅

notes get created, modified, or deleted as appropriate in your local database so it matches what's on the server. and if the specified database file doesn't exist, pnbackup will create it for you. self-sufficient queen 🎀

now, the tea ☕: the Pinboard API requires a three-second wait between each request, and the text of each note has to be downloaded in a separate request. so the initial download of your notes? might take a while. like, go make a snack, text your bestie back, hydrate 💧. subsequent syncs will generally be much shorter though — depends on how often you add or modify notes, and how often you run pnbackup. ngl the more consistent you are, the chiller it is 🧚

---

⭐ EXIT STATUS ⭐

pnbackup will return zero on success or nonzero on failure. that's it, that's the whole section. slay 💀

---

🍓 EXAMPLE 🍓

pnbackup -t maciej:abc123456 Notes.sqlite

this will put all of your notes into a SQLite database called Notes.sqlite — assuming your Pinboard username is maciej and your API token is abc123456. (they're not, obviously, but you get the vibe 🙈)

---

🔥 DATA FORMAT 🔥

the notes are stored in a SQLite database. the database contains a single table, notes, which has the following schema:

CREATE TABLE notes (
    id TEXT NOT NULL UNIQUE,
    title TEXT NOT NULL,
    text TEXT NOT NULL,
    hash TEXT NOT NULL,
    created DATETIME NOT NULL,
    updated DATETIME NOT NULL
);

these columns correspond exactly to the fields listed on the Pinboard API page (https://pinboard.in/api/). like, character for character, no creative liberties taken 💖

so, SQLite is a binary format — but there is a large ecosystem of tools that can work with it and, if you prefer, convert it to some text-based format instead. highkey a whole world of options 🌍

for example, if you've backed up your notes to a file called Notes.sqlite, you could use this quick and dirty Python script to print them in JSON format:

#!/usr/bin/env python3
from json import dumps
import sqlite3
conn = sqlite3.connect("Notes.sqlite")
conn.row_factory = sqlite3.Row
curs = conn.cursor()
curs.execute("SELECT * FROM notes")
print(dumps([dict(r) for r in curs.fetchall()]))

quick and dirty but it ATE 🔥

---

👑 AUTHOR 👑

this program was created by Benjamin Esham (https://esham.io). we stan a builder 🫶

---

🌈 WEBSITE 🌈

the project is hosted at <https://github.com/bdesham/pinboard-notes-backup> — go say hi, star it, the whole routine ⭐

---

💜 LICENSE 💜

Copyright © 2016–2017, 2019, 2021–2025 Benjamin D. Esham.

this program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

this program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. like, don't come for them if it breaks, fr fr 😭. see the GNU General Public License for more details.

you should have received a copy of the GNU General Public License along with this program. if not, see <http://www.gnu.org/licenses/>.

---

aaaand that's the whole page bestie 💖 this was pinboard-notes-backup, PNBACKUP(1), brought to you by the fine folks who make man pages render in your terminal at 2am. go back up your notes, hydrate, and remember: one-way sync only, she never writes to the server, iykyk 🦋💅✨