raindrop.rb

raindrop is a Ruby command line client for Raindrop.io.

It is built for everyday bookmark workflows from the terminal: authenticate with OAuth, search saved raindrops, inspect an item, add new links, update metadata, delete old ones, and list tags or collections.

Install the gem:

gem install raindrop

Then check that the executable is available:

raindrop --help

All URLs, IDs, names, and metadata in the examples are fictitious and do not refer to data from a real Raindrop.io account.

Create an OAuth application in Raindrop.io and register this Redirect URL:

http://127.0.0.1:42813/callback

Log in with your OAuth client credentials:

raindrop auth login \
  --client-id CLIENT_ID \
  --client-secret CLIENT_SECRET

Search your saved raindrops:

raindrop search example

Inspect a raindrop:

raindrop get 1234567890

Add a new link:

raindrop add https://example.com/article

Update an existing raindrop:

raindrop update 1234567890 --title "Example Article" --tag example

raindrop supports OAuth authentication. Test token authentication is not supported.

The default OAuth Redirect URL is:

http://127.0.0.1:42813/callback

When you run auth login, the CLI prints an authorization URL and starts a temporary local callback server on 127.0.0.1:42813. Open the URL in your browser, authorize the app, and Raindrop.io redirects back to the local callback URL. The CLI then exchanges the authorization code for OAuth tokens and stores them in the config file.

raindrop auth login \
  --client-id CLIENT_ID \
  --client-secret CLIENT_SECRET

If your OAuth application uses a different Redirect URL, pass it explicitly:

raindrop auth login \
  --client-id CLIENT_ID \
  --client-secret CLIENT_SECRET \
  --redirect-uri http://127.0.0.1:42813/callback

Check the current authentication status:

raindrop auth status

Remove stored OAuth credentials:

raindrop auth logout

Use --json to output API results as JSON. This option is available for search, get, add, update, delete, tags rename, tags merge, and tags remove.

raindrop search example --json

Search saved raindrops:

raindrop search example

By default, search returns up to 50 items. You can specify a smaller limit:

raindrop search example --limit 20

Sort results:

raindrop search example --sort score
raindrop search example --sort -created
raindrop search example --sort title

Supported sort values are -created, created, score, -sort, title, -title, domain, and -domain. score requires a search query.

Fetch all matching pages with --all:

raindrop search example --all

--all waits one second between pages to avoid sending requests too aggressively. It cannot be combined with --limit.

Filter by tag:

raindrop search --tag example
raindrop search example --tag reference --tag tutorial

Filter by collection:

raindrop search --collection 12345678
raindrop search example --collection 12345678

When --collection is provided, the search query itself is optional.

Show a single saved raindrop:

raindrop get 1234567890

Add a URL:

raindrop add https://example.com/article

Add a URL with metadata:

raindrop add https://example.com/article \
  --title "Example Article" \
  --description "Example article description" \
  --note "Read later" \
  --tag example \
  --tag reference \
  --collection 12345678

Update a saved raindrop by ID:

raindrop update 1234567890 \
  --title "Example Article" \
  --description "Example article description" \
  --note "Read later" \
  --tag example \
  --tag reference \
  --collection 12345678

At least one update option is required. Tags replace the raindrop's tag list with the tags passed on the command line.

Delete a saved raindrop by ID:

raindrop delete 1234567890

List tags:

raindrop tags

Rename a tag in all collections:

raindrop tags rename old-tag new-tag

Restrict the rename to one collection:

raindrop tags rename old-tag new-tag --collection 12345678

When --collection is omitted, the tag is renamed across all collections. The old and new tag names must be different.

Merge two or more tags into one tag:

raindrop tags merge old-tag legacy-tag --into new-tag

Restrict the merge to one collection:

raindrop tags merge old-tag legacy-tag --into new-tag --collection 12345678

When --collection is omitted, the tags are merged across all collections. Duplicate source tags and the destination tag are removed from the source list, and at least two source tags must remain.

Remove one or more tags from all collections:

raindrop tags remove unused-tag temporary-tag

Restrict the removal to one collection:

raindrop tags remove unused-tag temporary-tag --collection 12345678

When --collection is omitted, the tags are removed across all collections. This command does not prompt for confirmation, and removal cannot be undone through the Tags API.

Show the available tag management commands:

raindrop tags --help

List collections:

raindrop collections

The config file is stored under the XDG config directory. By default, this is:

~/.config/raindrop-cli/config.yml

Show the actual config path:

raindrop config path

Show config status:

raindrop config

Example output:

Auth: oauth
Access token: [REDACTED]
Refresh token: [REDACTED]
Token type: Bearer
Expires in: 3600

Access tokens and refresh tokens are never printed by raindrop config.

Install dependencies:

bundle install

Run the CLI from the working tree:

bin/raindrop --help

Run tests:

bundle exec rake test

Build the gem locally:

bundle exec gem build raindrop.gemspec

MIT