openclaw-instapaper

OpenClaw plugin for Instapaper reading list management. Provides 16 tools for managing bookmarks, folders, highlights, tags, and article text through OpenClaw.

Built on instapaper-cli, a full-featured Go CLI for the Instapaper API.

Quick Start

# 1. Install the CLI
brew tap vburojevic/tap && brew install instapaper-cli

# 2. Set credentials (get yours at https://www.instapaper.com/main/request_oauth_consumer_token)
export INSTAPAPER_CONSUMER_KEY="your-key"
export INSTAPAPER_CONSUMER_SECRET="your-secret"

# 3. Log in (one-time)
printf '%s' "your-password" | instapaper-cli auth login -username "you@example.com" -password-stdin

# 4. Install the plugin
openclaw plugins install instapaper-cli

Prerequisites

instapaper-cli binary

The plugin wraps the instapaper-cli Go binary. Install via Homebrew:

brew tap vburojevic/tap && brew install instapaper-cli

Verify: instapaper-cli version

The binary installs to /opt/homebrew/bin/instapaper-cli on Apple Silicon Macs. Ensure this is in your PATH.

Instapaper API credentials

Request an OAuth consumer token at https://www.instapaper.com/main/requestoauthconsumer_token

You will receive a consumer key and consumer secret. Keep these — you'll need them for authentication and plugin configuration.

Authentication (one-time)

export INSTAPAPER_CONSUMER_KEY="your-key"
export INSTAPAPER_CONSUMER_SECRET="your-secret"
printf '%s' "your-password" | instapaper-cli auth login -username "you@example.com" -password-stdin

This exchanges your credentials for OAuth tokens stored locally. You only need to do this once.

Verify: instapaper-cli auth status (should show logged_in: true)

Instapaper passwords are optional. If your account has no password, any value will work.

Install

From ClawHub

openclaw plugins install instapaper-cli

Or for local development:

openclaw plugins install -l ~/path/to/openclaw-instapaper

Symlink installs stay live with git pull updates.

Security note

This plugin uses Node.js execFile (not shell exec) to call the instapaper-cli binary. OpenClaw's static analysis scanner flags this at install time. If prompted, review the source code and use:

openclaw plugins install instapaper-cli --dangerously-force-unsafe-install

This is expected for any CLI-wrapper plugin. The plugin never executes arbitrary commands, only calls the instapaper-cli binary with structured arguments.

Configuration

The plugin needs your consumer key and secret at runtime to sign API requests. Choose one method:

Option A: SecretRef via secrets.json (recommended)

Add your credentials to ~/.openclaw/secrets.json:

{
  "plugins": {
    "instapaper": {
      "consumerKey": "your-key",
      "consumerSecret": "your-secret"
    }
  }
}

Then wire the SecretRefs:

openclaw config set plugins.entries.instapaper-cli.config.consumerKey \
  --ref-source file --ref-provider secrets --ref-id /plugins/instapaper/consumerKey
openclaw config set plugins.entries.instapaper-cli.config.consumerSecret \
  --ref-source file --ref-provider secrets --ref-id /plugins/instapaper/consumerSecret

Option B: macOS Keychain

security add-generic-password -s 'env/INSTAPAPER_CONSUMER_KEY' -a "$USER" -w 'your-key'
security add-generic-password -s 'env/INSTAPAPER_CONSUMER_SECRET' -a "$USER" -w 'your-secret'

openclaw config set plugins.entries.instapaper-cli.config.consumerKey \
  '{"source":"exec","provider":"keychain","id":"env/INSTAPAPER_CONSUMER_KEY"}' --strict-json
openclaw config set plugins.entries.instapaper-cli.config.consumerSecret \
  '{"source":"exec","provider":"keychain","id":"env/INSTAPAPER_CONSUMER_SECRET"}' --strict-json

Option C: Environment variables

# Add to your gateway environment or ~/.openclaw/.env
INSTAPAPER_CONSUMER_KEY=your-key
INSTAPAPER_CONSUMER_SECRET=your-secret

Resolution order

The plugin resolves credentials from these sources (first match wins):

Restart and verify

openclaw gateway restart

Test by asking your agent: "Save https://example.com to Instapaper"

Tools

Bookmarks

Folders

Highlights & Tags

Examples

instapaper_list { folder: "starred", limit: 10 }
instapaper_add { url: "https://example.com/article", tags: "tech,ai" }
instapaper_import { urls: ["https://a.com", "https://b.com"], folder: "Work" }
instapaper_text { bookmark_id: 12345678 }
instapaper_highlights_list { bookmark_id: 12345678 }

Architecture

All tools shell out to the instapaper-cli binary via execFile. The plugin:

1. Resolves consumer key/secret from config, env vars, or keychain
2. Passes them as environment variables to the CLI process (never touches shell history)
3. Parses ndjson or JSON output from the CLI
4. Returns structured results to OpenClaw

The CLI handles OAuth 1.0a request signing (HMAC-SHA1) and token management internally. User OAuth tokens persist in ~/.config/ip/ from the one-time auth login step.

Troubleshooting

License

MIT