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

Put Raindrop credentials in environment variables or a local env file.
Use either a test token or the built-in OAuth flow.
Run whoami first when verifying a new setup.
Use collections to discover target collection ids.
Use bookmarks and --search to inspect existing saved links.
Use create-collection, update-collection, and delete-collection for organization.
Use add-bookmark, update-bookmark, and delete-bookmark for individual saved links.
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 <id> — inspect one collection
create-collection --title NAME — create a collection
update-collection <id> ... — update a collection
delete-collection <id> — delete a collection
bookmarks <collectionId> [--search TEXT] — list/search bookmarks in a collection
bookmark-get <id> — inspect one bookmark
add-bookmark --collection-id ID --link URL — save a bookmark
update-bookmark <id> ... — edit a bookmark
delete-bookmark <id> — delete a bookmark
export-bookmarks <collectionId> --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