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

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 ruby

Inspect a raindrop:

raindrop get 1352782792

Add a new link:

raindrop add https://www.ruby-lang.org/

Update an existing raindrop:

raindrop update 1352782792 --title "Ruby" --tag ruby

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

Search saved raindrops:

raindrop search ruby

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

raindrop search ruby --limit 20

Sort results:

raindrop search ruby --sort score
raindrop search ruby --sort -created
raindrop search ruby --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 ruby --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 Auth
raindrop search ruby --tag docs --tag rails

Filter by collection:

raindrop search --collection 55596991
raindrop search ruby --collection 55596991

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

Output JSON:

raindrop search ruby --json

Show a single saved raindrop:

raindrop get 1352782792

Output JSON:

raindrop get 1352782792 --json

Add a URL:

raindrop add https://www.ruby-lang.org/

Add a URL with metadata:

raindrop add https://www.ruby-lang.org/ \
  --title Ruby \
  --description "Ruby language" \
  --note "Read later" \
  --tag ruby \
  --tag docs \
  --collection 55596991

Output JSON:

raindrop add https://www.ruby-lang.org/ --json

Update a saved raindrop by ID:

raindrop update 1352782792 \
  --title Ruby \
  --description "Ruby language" \
  --note "Read later" \
  --tag ruby \
  --tag docs \
  --collection 55596991

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

Output JSON:

raindrop update 1352782792 --title Ruby --json

Delete a saved raindrop by ID:

raindrop delete 1352782792

Output JSON:

raindrop delete 1352782792 --json

List tags:

raindrop tags

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: 1209599

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