# Table of Contents

1.  [Introduction](#org2ed09e2)
2.  [License](#org3821e51)
3.  [Prerequistes](#org59add51)
4.  [Installation](#orge2db134)
5.  [Status & Roadmap](#org4b113ee)



<a id="org2ed09e2"></a>

# Introduction

[Pinboard](https://pinboard.in/) is "social bookmarking for introverts"&#x2013; a social bookmarking web service along the lines of (the now defunct) [del.icio.us](https://en.wikipedia.org/wiki/Delicious_(website)). [pin](https://github.com/sp1ff/pin) is a command-line client for [Pinboard](https://pinboard.in). It is by no means complete; it supports a few operations which I have found useful in my workflow. Here are a few examples:

You can send a link `http://foo.com/bar` to [Pinboard](https://pinboard.in) with title "splat" & tags `a`, `b` & `c` like so:

    pin send -t a -t b -t c "http://foo.com/bar | splat"

You can setup canned tag clouds you use repeatedly & refer to them by name:

    $> cat ~/.pin
    token = "you:XXX"
    
    [targets]
    
    [targets.frobnitz]
    tags = ["@review", "frobinate"]
    read_later = true
    ...
    # This link will get tags @review & frobinate, and have the "read later" flag set:
    $> pin send -r frobnitz "http://foo.com/bar | splat"

You can send the link to [Instapaper](https://www.instapaper.com) at the same time:

    $> pin send -r frobnitz --with-instapaper "http://foo.com/bar | splat"

I use it for curating my tags:

    $> pin get-tags 
    | Tag                            | Use Count |
    +--------------------------------+-----------+
    | flapdoodl                      |         1 |
    | flapdoodle                     |     10000 |
    ...
    # Hmmm... likely a mis-spelling
    $> pin rename-tag flapdoodl flapdoodle

or, say, deleting all links with a given combination of tags when they're no longer useful:

    ping delete old-company+jira

Type `pin --help` for a description of all flags & sub-commands.


<a id="org3821e51"></a>

# License

[pin](https://github.com/sp1ff/pin) is GPL v3 software.


<a id="org59add51"></a>

# Prerequistes

The Rust [toolchain](https://rustup.rs/) (Rust version 1.57 at minimum).


<a id="orge2db134"></a>

# Installation

This crate is available on [crates.io](https://crates.io), but you can also download an Autotools tarball:

    cd /tmp
    curl -O https://www.unwoundstack.com/dist/pin-0.2.8.tar.xz
    tar xf pin-0.2.8.tar.xz
    cd pin-0.2.8
    ./configure
    make
    make check
    sudo make install


<a id="org4b113ee"></a>

# Status & Roadmap

[pin](https://github.com/sp1ff/pin) is still early code; I have chosen the version number (0.2) in the hopes of conveying that this is a preliminary release. [pinboard.py](https://github.com/lionheart/pinboard.py) provides far more complete coverage of the Pinboard API, albeit at the cost of forcing users to navigate Python's package management. Still, [pin](https://github.com/sp1ff/pin) provides an interface that is task-oriented, not API-oriented. For instance, deleting all links with a given tag combination is actually a complex operation; one needs to:

-   ask the API for all links that have that combination of tags
-   delete those links one at a time (because that is what the API allows)
-   while respecting the API's rate limits

In other words, this package is intended to provide an interface organized around user operations, not API endpoints.

Bugs, comments, problems, PRs, feature requests &c welcome at [sp1ff@pobox.com](mailto:sp1ff@pobox.com) and in the [issues](https://github.com/sp1ff/pin/issues).