Raindrop.io Bookmark Downloader
A Python CLI tool for downloading bookmarks from Raindrop.io and converting them to markdown files with YAML frontmatter.
Overview
This skill helps you build a CLI application that downloads "raindrops" (bookmarks) from Raindrop.io and saves them as markdown files with structured metadata. The tool is designed to be idempotent and tracks previously downloaded items to avoid duplicates.
Core Features
Download all bookmarks from Raindrop.io via REST APITrack downloaded items to prevent re-downloadingIdempotent operation (delete output and re-run for identical results)Export to markdown with YAML frontmatterSupport for collections and multiple export formatsImplementation Steps
1. Project Setup
Set up a Python project using `uv` for dependency management:
```bash
uv init rd_dl
cd rd_dl
uv add requests pyyaml click
```
2. API Authentication
Obtain a Raindrop.io access token:
Visit https://developer.raindrop.ioCreate an application and generate an access tokenStore the token securely (environment variable or config file)3. Core CLI Structure
Create the main CLI application with these commands:
`rd_dl` - Download all bookmarks`rd_dl --collection <id>` - Download from specific collection`rd_dl --format <json|csv|html>` - Choose export format4. API Integration
Implement API calls to Raindrop.io endpoints:
**Collections endpoint**: Retrieve available collections**Raindrops endpoint**: Fetch bookmark dataHandle pagination for large bookmark setsImplement error handling and rate limiting5. Download Tracking
Create a tracking mechanism to prevent duplicate downloads:
Maintain a local database or JSON file of downloaded raindrop IDsCheck against this list before downloadingUpdate the list after successful downloads6. Markdown Export
Convert raindrop data to markdown files with this structure:
```markdown
---
title: "Bookmark Title"
date: 2024-01-15
tags: [tag1, tag2, tag3]
type: drop
---
[Bookmark content and description]
```
7. File Naming Convention
Save files in a `drops/` directory with the naming pattern:
`drop-yy-mm-dd-n.md` (e.g., `drop-24-01-15-1.md`)Increment `n` for multiple bookmarks on the same day8. Idempotent Design
Ensure the tool produces identical output when re-run:
Sort bookmarks by creation date before processingUse consistent naming based on bookmark metadataClear and rebuild the `drops/` directory on each run (optional mode)API Reference
**Base URL**: `https://api.raindrop.io/rest/v1`
**Key Endpoints**:
`GET /raindrops/{collection}` - Get raindrops from a collection`GET /collections` - List all collections`GET /user` - Get user information**Authentication**: Include access token in headers:
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```
Example Usage
```bash
Download all bookmarks
rd_dl
Download from specific collection
rd_dl --collection 12345
Export as JSON instead of markdown
rd_dl --format json
Force re-download all items
rd_dl --force
```
YAML Frontmatter Schema
Each markdown file should include:
`title`: Bookmark title`date`: Creation or modification date`tags`: Array of tags from Raindrop.io`type`: Always set to "drop"Optional: `url`, `excerpt`, `collection`, `created`Error Handling
Implement robust error handling for:
Network failures and timeoutsInvalid API tokensRate limiting (respect API limits)Missing or malformed bookmark dataFile system errorsTesting
Test the following scenarios:
Initial download of all bookmarksIncremental downloads (only new items)Re-running after deleting output (idempotent check)Collection-specific downloadsVarious export formatsDependencies
`requests`: HTTP library for API calls`pyyaml`: YAML parsing and generation`click` or `argparse`: CLI framework`python-dotenv`: Environment variable management (optional)Best Practices
1. **API Rate Limiting**: Respect Raindrop.io API limits
2. **Secure Token Storage**: Never commit tokens to version control
3. **Progress Indicators**: Show download progress for large collections
4. **Logging**: Implement logging for debugging and audit trails
5. **Configuration**: Support config files for default settings
Notes
The Raindrop.io API requires authentication for all requestsFree tier may have API rate limitsBookmark data includes URL, title, excerpt, tags, and timestampsCollections can be nested in Raindrop.io