ip5 — Instapaper “pick 5” triage CLI

ip5 is a small interactive CLI tool to quickly drain your Instapaper backlog.

It shows 5 random unread articles, lets you pick which ones are worth keeping, then:

• archives the selected ones
• opens them in your browser
• deletes the rest

Designed for fast, low-friction triage from a terminal.

---

Features

• Fetches unread bookmarks from Instapaper
• Random sampling (fast + biased, configurable)
• Clean terminal output (title + domain + URL)
• Interactive numeric selection (1 3 5)
• Fail-fast execution for proof-of-concept verification
• Uses Instapaper Full API with xAuth

---

Requirements

• Linux (tested on elementaryOS / Ubuntu)
• Python 3.10+
• Instapaper Full API access (consumer key & secret)
• Internet connection

Python dependencies

• requests
• requests-oauthlib

With uv:

uv run --with requests --with requests-oauthlib ip5.py

---

Installation

Clone or copy ip5.py somewhere on your $PATH, or run it directly:

chmod +x ip5.py
./ip5.py

---

Configuration

Config file (recommended)

Default location:

~/.config/ip5/config.ini

Example:

[auth]
consumer_key = YOUR_CONSUMER_KEY
consumer_secret = YOUR_CONSUMER_SECRET

On first run, ip5 will:

1. Prompt for your Instapaper username/password
2. Perform xAuth
3. Store the OAuth token + secret in this file

You only need to authenticate once.

Environment variables (optional)

Overrides config values if set:

• IP_CONSUMER_KEY
• IP_CONSUMER_SECRET
• IP_TOKEN
• IP_TOKEN_SECRET
• IP_USER
• IP_PASS
• BROWSER (browser command)

---

Usage

Basic run:

ip5

Example output:

1) Some Interesting Article
   nytimes.com
   https://www.nytimes.com/...

2) Another Link
   github.com
   https://github.com/...

Prompt:

Pick articles to keep (1-5, e.g. '1 3 5' or '2,4'), or 'q' to quit:
>

Then confirm:

Keep (archive + open): 1,3,5
Delete: 2,4
Proceed? [y/N]:

---

Options

| Flag | Description | | ---------------------- | -------------------------------------------------------- | | -n, --count N | Number of items to show (default: 5, max: 20) | | -k, --max-fetch K | Max unread items fetched before shuffling (default: 100) | | --no-open | Do not open URLs in browser | | --no-delete | Do not delete unselected bookmarks | | --no-confirm | Skip confirmation prompt | | --dry-run | Show plan only; no changes | | --browser CMD | Custom browser command | | --format plain\|json | Output format (plain default; JSON reserved) |

---

Execution semantics

• Order: archive → open → delete
• Fail-fast: any error aborts immediately
• Confirmation: required before deletion (unless --no-confirm)
• Empty input: reprompt
• q / quit: exit with no changes

---

Exit codes

| Code | Meaning | | ---- | --------------------------------- | | 0 | Success | | 1 | User quit / declined confirmation | | 2 | Invalid arguments | | 3 | Auth or list error | | 4 | Mutation or browser error |

---

Notes on excerpts

Instapaper bookmark description is often empty. For usability, ip5 displays:

• Title
• Full URL

This proved more useful than unreliable text excerpts.

---

Security notes

• Your OAuth token is stored locally in plain text.
• Do not commit config.ini.
• Prefer ~/.config/ip5/config.ini over storing secrets next to the script.

---

Status

This is a proof of concept with intentionally strict, fail-fast behavior. It is not intended to be a full Instapaper client.

---

License

MIT