Raindrop.io Bookmark Manager

Use the official Raindrop.io API through a local CLI that prefers user environment variables and can optionally read a local .env file outside the skill folder.

Secret storage

Store real credentials outside the skill folder.

Preferred approach:

• store RAINDROP_CLIENT_ID, RAINDROP_CLIENT_SECRET, RAINDROP_ACCESS_TOKEN, and optional RAINDROP_REFRESH_TOKEN as user environment variables

Optional fallback:

• set RAINDROP_ENV_FILE to point at a local env file if you explicitly want file-based storage

Rules:

• never hardcode real client ids, secrets, access tokens, or refresh tokens into the skill
• never publish real credential values in SKILL.md, references/, or scripts/
• prefer environment variables over passing secrets on the command line, because shell history may retain CLI arguments

The skill does not need secrets embedded inside the published skill folder.

Example env file shape is documented in:

• references/env-example.md

Quick start

Validate auth:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py whoami

Start OAuth without auto-opening the browser:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py auth-start --no-browser

Finish OAuth with the returned code:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py auth-finish --code "PASTE_CODE_HERE"

Refresh an OAuth token:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py refresh-token

List top-level collections:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py collections

List nested collections:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py collections --children

List bookmarks in a collection:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py bookmarks 0 --perpage 20

Search bookmarks inside a collection:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py bookmarks 0 --search "etsy" --perpage 20

Create a collection:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py create-collection --title "Research" --view list

Save one bookmark:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py add-bookmark --collection-id 123456 --link "https://example.com" --title "Example"

Export bookmark links:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py export-bookmarks 123456 --format csv --output ".\output\raindrop-export.csv"

Import bookmarks from a txt list:

python .\skills\raindrop-io-bookmark-manager\scripts\raindrop_manager.py import-bookmarks --input ".\input\urls.txt" --collection-id 123456 --output ".\output\results.json"

Workflow

1. Put Raindrop credentials in environment variables or a local env file.
2. Use either a test token or the built-in OAuth flow.
3. Run whoami first when verifying a new setup.
4. Use collections to discover target collection ids.
5. Use bookmarks and --search to inspect existing saved links.
6. Use create-collection, update-collection, and delete-collection for organization.
7. Use add-bookmark, update-bookmark, and delete-bookmark for individual saved links.
8. Use import-bookmarks and export-bookmarks for batch workflows.

Commands

• whoami — verify auth and inspect account info
• auth-start [--no-browser] — generate the OAuth authorize URL
• auth-finish --code CODE — exchange an OAuth code for tokens and save them locally
• refresh-token — refresh OAuth tokens and save them locally
• collections [--children] — list root or nested collections
• collection-get — inspect one collection
• create-collection --title NAME — create a collection
• update-collection ... — update a collection
• delete-collection — delete a collection
• bookmarks [--search TEXT] — list/search bookmarks in a collection
• bookmark-get — inspect one bookmark
• add-bookmark --collection-id ID --link URL — save a bookmark
• update-bookmark ... — edit a bookmark
• delete-bookmark — delete a bookmark
• export-bookmarks --format json|txt|csv --output file — export bookmarks
• import-bookmarks --input file --collection-id ID — import bookmarks from txt or json
• env-template — print or write a local env template

List/export commands support extra filters like:

• --tag
• --domain
• --contains

Many commands also support --csv for flatter stdout output.

OAuth / callback note

For a local desktop-style setup, use:

• http://127.0.0.1:8765/callback

Optionally also add:

• http://localhost:8765/callback

For local-only automation, a Raindrop test token is often enough and simpler than interactive OAuth.

Resources

scripts/

• raindrop_manager.py — local Raindrop.io CLI for auth, collections, bookmarks, import, and export

references/

• api-notes.md — endpoint notes and field reminders
• env-example.md — non-secret example of the local env file shape