# Instapaper

> Use when operating the instapaper-cli (ip) tool or troubleshooting it: authenticating, listing/exporting/importing bookmarks, bulk mutations, folders/highlights/text, choosing output formats (ndjson/json/plain), cursor-based sync, and interpreting stderr-json/exit codes for automation.

- Skill: `kbarbel640-del/instapaper` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kbarbel640-del/instapaper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kbarbel640-del/instapaper/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kbarbel640-del (https://skillmd.com/u/kbarbel640-del)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/kbarbel640-del/instapaper

---


# Instapaper CLI

## Overview

Use this skill to handle Instapaper operations via the `ip` CLI (which must be installed and available in `PATH`), especially when you need reliable automation, structured output, or troubleshooting guidance.

## Install the CLI

- Go install: `go install github.com/vburojevic/instapaper-cli/cmd/ip@latest`
- Homebrew: `brew tap vburojevic/tap && brew install instapaper-cli`
- From source: `go build ./cmd/ip` (run as `./ip`)

## Workflow (fast path)

1. Verify setup
   - Ensure `INSTAPAPER_CONSUMER_KEY` and `INSTAPAPER_CONSUMER_SECRET` are set or passed during login.
   - Prefer `--password-stdin` for auth; never store the password.
   - Run `ip doctor --json` (or `ip auth status`) before long jobs.

2. Pick output format for automation
   - Default is `--ndjson` (streaming, one object per line).
   - Use `--json` for single objects or compact arrays.
   - Use `--plain` for stable, line-oriented text.
   - Add `--stderr-json` for structured errors and `--progress-json` for long runs.

3. Read data deterministically
   - Use `list` or `export` with `--cursor`/`--cursor-dir` or `--since/--until` bounds.
   - Use `--updated-since` for incremental sync.
   - Use `--select` for client-side filtering when the API does not support it.

4. Mutate safely
   - Use `--dry-run` or `--idempotent` when possible.
   - For bulk actions, use `--ids` or `--stdin` and consider `--batch`.
   - Deletions require explicit confirmation flags.

5. Handle extras
   - Text view: `ip text` for article HTML.
   - Highlights: `ip highlights list/add/delete`.
   - Folders: `ip folders list/add/delete/order`.

6. Troubleshoot
   - Use `--debug` for request timing and status.
   - Use `--stderr-json` and map `exit_code` to action.

## Command reference

Read these when you need exact flags, formats, or examples:

- `references/commands.md`: command-by-command examples for auth, list/export/import, mutations, folders, highlights, and text.
- `references/output-and-sync.md`: output formats, progress streams, cursor/bounds syntax, and filtering.
- `references/errors.md`: exit codes and structured stderr error codes.

## Guardrails

- Avoid `--format table` for parsing; it is for humans only.
- Use `--output` or `--output-dir` for large exports to avoid stdout pressure.
- Prefer `--password-stdin` on Windows to avoid echoing passwords.