pin ¶

2.1 Sending Links to Pinboard ¶

The original use case for pin was sending links to Pinboard from the command line, or in situations where the only interface available was process-based.

In Pinboard terms, a link is a “post”, or a “bookmark”, and it has certain attributes. The two mandatory attributes are:

1. url The URL being saved, as defined in RFC3986. Allowed schemes are http, https, javascripts, mailto, ftp & file.
2. description The display name for the link. Per the API docs, “This field is unfortunately named ’description’ for backwards compatibility with the delicious API” The description must be fewer than 256 characters in length (see Technical Details).

A post has several other optional attributes. pin supports the following:

1. tags Zero or more tags, each less than 256 characters in length and may not contain commas or whitespace. Tags beginning with a ’.’ are “private”.
2. toread Mark the post as “unread”.

The relevant sub-command is ’send’, with arguments being the link or links you’d like to send to Pinboard. The links may be given in one of two ways. The first is simply giving the URL as an argument, in which case the title will be taken from the -T or --title option (which must be provided, in this case; it is illegal to send a link with no title):

pin send --title=foo http://foo.com

The other is to give arguments in the form “URL | TITLE” in which case the title given for each argument will be preferred to the --title

pin send "http://foo.com | foo"

The latter form happens to be the export format of the One Tab FireFox plugin.

You can tag the links given as arguments as “to be read later” by adding the --read-later. You can tags the links given with the --tag option (which can of course be given more than once).

• Instapaper
• Targets

[targets]

[targets.tech]
tags = ["@review-tech"]
read_later = true
send_to_insty = false

[targets.long-form]
tags = ["@review-long-form"]
read_later = true
send_to_insty = true

pin send --tag=@review-long-form --read-later --with-instapaper "https://foo.com | Think Piece"

pin send --target=long-form "https://foo.com | Think Piece"

2.2 Deleting Links ¶

Sometimes, you may want to delete links. The author, for instance, uses Pinboard as a reference library that sometimes includes links to documents only available on an employer’s VPN. Once that employer has been left, those documents are no longer available (or, frankly, of interest).

One can of course delete links directly, simply by saying pin delete URL..., but this is likely to prove tedious. Therefore, you can also delete by tags.

To remove all links with a given tag, say:

pin delete TAG

You can combine tags with the ’+’ symbol; this will select the set of URLs who have all of the tags in the expression:

pin delete TAG1+TAG2+TAG3

will only delete links with all of TAG1, TAG2 and TAG3.

You can freely mix tags & URLs as arguments, like so:

pin delete https://foo.com TAG1+TAG2+TAG3 http://bar.io TAG4

Since the Pinboard API only allows deleting a single post at a time, this sub-command can result in a flood of API invocations subject to rate-limiting, and so this command may take some time to complete. If verbose output has not been requested, a progress bar will be displayed (see Rate Limiting).

If you’d like to just see a list of links that would be deleted, specify the --dry-run flag.

2.3 Reporting On Your Tags ¶

The author has found that without regular curation, his tag collection decays; typos creep in, similar tags are created to name the same abstraction, and so forth. Periodically, one may want to get a report one one’s tags.

pin get-tags will do so. It will fetch all of the user’s tags from Pinboard and print them in a a few formats. By default, it will produce an Emacs Org Mode-like table, but the --csv option will instead cause it to produce output in Comma-Separated Values format.

By default, the tags are sorted numerically by use; use the alphabetical option to sort lexicographically.

By default, the tags are sorted in ascending order (whether numerically or lexicographically); use the --descending option to reverse that.

2.4 Renaming Tags ¶

Having discovered a typo in one’s tagging scheme, one may wish to correct it: just say pin rename-tag OLD NEW to rename all instances of the old tag name to the new.

3.1 Providing Your Credentials ¶

Pinboard API callers may authenticate using the HTTP Basic Authentication scheme with the credentials provided in the URL (i.e. ‘https://username:password@api.pinboard.in/v1/method’) or with an API key provided in the query parameters (i.e. ‘https://api.pinboard.in/v1/method?auth_token=user:NNNNNN’). Given the obvious security concerns in the former, pin only supports the latter. You can find your API key here once you’ve signed-up & logged-in.

You can provide that token to pin in one of the following three ways:

1. Specify it in the --token global option
2. Specify it in the PINBOARD_API_TOKEN environment variable
3. Specify it in your configuration file. If you choose this root, you should be careful to set the file permission on that file appropriately (600, for instance).

Instapaper credentials may be provided as parameters to the send sub-command, in the environment variables INSTAPAPER_USERNAME and INSTAPAPER_PASSWORD or in the configuration file (see The Configuration File).

3.2 The Configuration File ¶

pin offers many options. The user may find it convenient to collect some of them in a configuration file (~/.pin by default) that will be read by the tool on invocation rather than specifying them every time on the command line.

The configuration file is in TOML format, and all items are optional:

1. version File format version (zero by default).
2. token The user’s Pinboard token.
3. username The user’s Instapaper username.
4. password The user’s Instapaper password
5. targets

   Targets (see Targets) are specified in their own section “[targets]”, and each target has its own section “[targets.NAME]” (see below for an example). Each target may have one or more of the following attributes:

   1. tags A vector of Tags, encoded as strings.
   2. read_later A boolean indicating whether or not posts sent to this target should be tagged as “to be read later”.
   3. send_to_insty A boolean indicating whether links sent to this target should also be sent to Instapaper.

A complete sample configuration file:

# Instapaper username
username = "jdoe@gmail.com"
# Pinboard API token
token ="jdoe:DECADE90C0DEDDABB1ED"

[targets]

[targets.tech]
tags = ["@review-tech", "tech"]
read_later = true
send_to_insty = false

4.1 Encodings ¶

All textual entities shall be UTF-8 encoded. The API docs state that “’characters’ means logical characters rather than bytes”. pin interprets that to mean grapheme clusters and uses the unicode_segmentation crate to identify them.

4.2 Rate Limiting ¶

Both the Pinboard & Instapaper APIs reserve the right to rate-limit callers. In the case of Pinboard, the advertised acceptable rate for most endpoints is one request every three seconds (much worse for a few selected endpoints), but the author has seen far better than that in the wild. The docs suggest: “Make sure your API clients check for 429 Too Many Requests server errors and back off appropriately. If possible, keep doubling the interval between requests until you stop receiving errors.”

Instapaper is a bit more coy, only alluding to rate-limiting in their documentation for a 400 response code as being returned for “a bad request or exceeded the rate limit”. The rate limit is never defined, and the author has never encountered it in the wild.

Regardless, this implementation will take into account the possibility of rate-limiting by retrying on certain status codes, halving the request rate each time.