.\" Automatically generated by Pandoc 2.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "PNBACKUP" "1" "" "pinboard-notes-backup" ""
.hy
.SH NAME
.PP
\f[B]pinboard-notes-backup\f[R] \[en] Back up the notes you\[cq]ve saved
to Pinboard
.SH SYNOPSIS
.PP
\f[B]pnbackup\f[R]
\f[V][-v | --verbose] -t <username>:<api token> <output file>\f[R]
.SH OPTIONS
.PP
The following parameters must always be given:
.TP
\f[V]-t <username>:<api token>\f[R]
Your Pinboard username, a colon, and your Pinboard API token.
You can find this on the Pinboard password settings page
(https://pinboard.in/settings/password).
.TP
\f[V]<output file>\f[R]
The name of the SQLite database file where your notes will be stored.
This file will be created if it doesn\[cq]t yet exist.
.PP
The following options are available:
.TP
\f[V]-v, --verbose\f[R]
Display more information about the sync progress.
.TP
\f[V]-h, --help\f[R]
Display the usage information and exit.
.TP
\f[V]--version\f[R]
Display the version number and exit.
.SH DESCRIPTION
.PP
The program performs one-way synchronization between Pinboard and a
local database: it will update your local file to match what\[cq]s on
the server but it will never make any changes on the server.
Notes will be created, modified, or deleted as appropriate in your local
database to match what\[cq]s on the server.
If the specified database file doesn\[cq]t exist, pnbackup will create
it for you.
.PP
The Pinboard API requires a three-second wait between each request, and
the text of each note must be downloaded in a separate request, so the
initial download of your notes may take a while.
Subsequent syncs will generally be much shorter, depending on how often
you add or modify notes and how often you run pnbackup.
.SH EXIT STATUS
.PP
pnbackup will return zero on success or nonzero on failure.
.SH EXAMPLE
.TP
\f[V]pnbackup -t maciej:abc123456 Notes.sqlite\f[R]
will put all of your notes into a SQLite database called
\[lq]Notes.sqlite\[rq], assuming that your Pinboard username is
\[lq]maciej\[rq] and your API token is \[lq]abc123456\[rq].
.SH DATA FORMAT
.PP
The notes are stored in a SQLite database.
The database contains a single table, \[lq]notes\[rq], which has the
following schema:
.IP
.nf
\f[C]
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
);
\f[R]
.fi
.PP
These columns correspond exactly to the fields listed on the Pinboard
API page (https://pinboard.in/api/).
.PP
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.
For example, if you\[cq]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:
.IP
.nf
\f[C]
#!/usr/bin/env python3
from json import dumps
import sqlite3
conn = sqlite3.connect(\[dq]Notes.sqlite\[dq])
conn.row_factory = sqlite3.Row
curs = conn.cursor()
curs.execute(\[dq]SELECT * FROM notes\[dq])
print(dumps([dict(r) for r in curs.fetchall()]))
\f[R]
.fi
.SH AUTHOR
.PP
This program was created by Benjamin Esham (https://esham.io).
.SH WEBSITE
.PP
The project is hosted at
<https://github.com/bdesham/pinboard-notes-backup>.
.SH LICENSE
.PP
Copyright \[co] 2016\[en]2017, 2019, 2021\[en]2025 Benjamin D.\ Esham.
.PP
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.
.PP
This program is distributed in the hope that it will be useful, but
\f[B]without any warranty;\f[R] without even the implied warranty of
\f[B]merchantability\f[R] or \f[B]fitness for a particular purpose.\f[R]
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
with this program.
If not, see <http://www.gnu.org/licenses/>.