pin

Manage your Pinboard links.

This manual corresponds to pin version 0.2.5.

Table of Contents


1 Introduction

Pinboard is "social bookmarking for introverts"– a social bookmarking web service along the lines of (the now defunct) del.icio.us. pin is a command-line client for Pinboard. With it, you can send links to Pinboard (among other tasks) programmatically, or perform operations that are inconvenient from the web application such as generate a report on your tags.

The author, for instance, uses it, along with Emacs org-protocol, to capture links from the browser and store them simultaneously in his notes and on Pinboard.


2 Things You Can Do With the Program


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 Configuration


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 Technical Details


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.


5 Roadmap & Contributing

pin is still early code; its version number 0.2.5 is selected to indicate that.

The package is intended to provide an interface organized around user operations, not API endpoints, so new operations will be added when & as they are requested.

Bugs, comments, problems, PRs, feature requests &c welcome at , Github or shoot a webmention to me at my web site.


Index