playbooks

home / skills / openclaw / skills / instapaper

instapaper skill

/skills/vburojevic/instapaper

This skill helps automate and troubleshoot Instapaper CLI operations, providing deterministic output, safe mutations, and structured error guidance for ip

npx playbooks add skill openclaw/skills --skill instapaper

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.6 KB
---
name: instapaper
description: "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."
---

# 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.

Overview

This skill helps you operate and troubleshoot the instapaper-cli (ip) tool for automating Instapaper tasks like authentication, export/import, bulk mutations, folders, highlights, and text retrieval. It focuses on deterministic output formats, cursor-based sync, and interpreting structured stderr/exit codes so you can build reliable pipelines. Use it when you need repeatable backups, scripted edits, or robust error handling for CI/automation.

How this skill works

The skill inspects and explains ip flags, recommended environment variables, and output modes (ndjson, json, plain) so you can choose the best format for automation. It guides using cursor/updated-since bounds, batch/ids/stdin mutation paths, and safety features like dry-run and idempotent modes. It also covers using --stderr-json and progress streams to map exit codes and structured errors into automated responses.

When to use it

  • Automating full or incremental backups of bookmarks and highlights
  • Scripting bulk mutations (move, delete, archive) safely in batches
  • Troubleshooting auth, network, or unexpected exit codes in CI
  • Exporting stable machine-readable output for downstream tools
  • Fetching article text or highlights for processing or ingestion

Best practices

  • Verify environment and auth with ip doctor --json or ip auth status before long jobs
  • Prefer --ndjson for streaming, --json for single objects, and --plain for stable line-oriented text
  • Use --password-stdin to avoid password leakage and never store plaintext passwords
  • Perform destructive actions with --dry-run, --idempotent, and explicit confirmation flags
  • Use --output-dir or --output to avoid stdout pressure for large exports and avoid --format table for parsing

Example use cases

  • Run cursor-based incremental sync: ip export --ndjson --updated-since 2024-01-01 --cursor-dir ./cursors
  • Bulk-delete a set of IDs safely: ip delete --ids $(cat ids.txt) --batch 100 --dry-run then repeat without dry-run
  • Automate CI checks by parsing --stderr-json and mapping exit_code to alerting logic
  • Export all highlights and article text: ip highlights list --ndjson > highlights.ndjson; ip text --ids ... --output-dir ./texts
  • Import a curated ndjson backup with ip import --stdin --idempotent --batch 50 to avoid duplicates

FAQ

Which output format should I choose for automation?

Use --ndjson for streaming large datasets, --json for compact single objects or arrays, and --plain when you need stable line-oriented text. Add --stderr-json and --progress-json for structured errors and progress.

How do I perform safe bulk mutations?

Use --ids or --stdin with --batch and start with --dry-run or --idempotent. Require explicit confirmation flags for deletions and test on a small subset first.

How do I handle authentication securely?

Set INSTAPAPER_CONSUMER_KEY/SECRET in the environment and use --password-stdin for user password input. Run ip doctor --json to validate credentials before large operations.