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

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

3. Core CLI Structure

Create the main CLI application with these commands:

4. API Integration

Implement API calls to Raindrop.io endpoints:

5. Download Tracking

Create a tracking mechanism to prevent duplicate downloads:

6. 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:

8. Idempotent Design

Ensure the tool produces identical output when re-run:

API Reference

**Base URL**: `https://api.raindrop.io/rest/v1`

**Key Endpoints**:

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

Error Handling

Implement robust error handling for:

Testing

Test the following scenarios:

Dependencies

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