--- name: puddle description: CLI for Raindrop.io bookmark management - search, create, update, delete, bulk operations. Use when working with Raindrop.io bookmarks or when the user mentions bookmarks, link saving, or Raindrop. license: MIT compatibility: Requires bash 4+, curl, jq --- # puddle Bash CLI for managing Raindrop.io bookmarks. Designed for AI agents to programmatically manage bookmarks. ## Usage **IMPORTANT**: Use the bundled script, not a global `puddle` command: ```bash .\/scripts\/puddle [options] ``` All examples below assume you're running from the skill's base directory. ## Setup ```bash # Set token (get from https:\/\/app.raindrop.io\/settings\/integrations) export RAINDROP_TOKEN="your-token" # Or save to config file mkdir -p ~\/.config\/puddle echo "your-token" > ~\/.config\/puddle\/token ``` ## Commands | Command | Description | |---------|-------------| | `.\/scripts\/puddle ls [search]` | List\/search bookmarks | | `.\/scripts\/puddle get ` | Get single bookmark | | `.\/scripts\/puddle add ` | Create bookmark | | `.\/scripts\/puddle update ` | Update bookmark | | `.\/scripts\/puddle rm ` | Delete bookmark | | `.\/scripts\/puddle tag add\|rm --search '...'` | Bulk tag operations | | `.\/scripts\/puddle move --search '...'` | Bulk move bookmarks | | `.\/scripts\/puddle collections` | List all collections | ## Quick Examples ```bash # Search by tag .\/scripts\/puddle ls '#react' # Search by type .\/scripts\/puddle ls 'type:article' # Add bookmark with metadata .\/scripts\/puddle add 'https:\/\/example.com' --title 'Example' --tags 'dev,reference' --collection 12345 # Update bookmark .\/scripts\/puddle update 12345 --tags 'updated,tags' --important true # Bulk tag all matching bookmarks .\/scripts\/puddle tag add 'archived' --search 'created:<2024-01-01' # Move bookmarks to collection .\/scripts\/puddle move 67890 --search '#old-project' # Get collection IDs .\/scripts\/puddle collections | jq '.[] | {id: ._id, title}' ``` ## Command Options ### `ls [search]` ``` --collection Filter by collection (default: all) --page Page number (default: 0) --perpage Results per page (default: 25) ``` ### `add ` ``` --title Override auto-detected title --tags Comma-separated tags --collection Target collection --excerpt Description\/excerpt ``` ### `update ` ``` --title New title --note Agent note field --tags Replace all tags --excerpt New description --collection Move to collection --important true|false Mark as favorite ``` ### `tag add|rm ` ``` --search Required: search query for matching bookmarks --collection Limit to collection (default: all) ``` ### `move ` ``` --search Required: search query for matching bookmarks --collection Source collection (default: all) ``` ## Search Syntax Quick Reference | Syntax | Example | Description | |--------|---------|-------------| | `#tag` | `#react` | Filter by tag | | `type:X` | `type:article` | Filter by type (article, video, image, document, audio, link) | | `created:>DATE` | `created:>2024-01-01` | Created after date | | `created:2024-01-01` For complex queries, see [references\/search-dsl.md](references\/search-dsl.md). ## Output Processing with jq ```bash # Extract URLs only .\/scripts\/puddle ls '#react' | jq -r '.[].link' # Get titles and IDs .\/scripts\/puddle ls 'type:video' | jq '.[] | {id: ._id, title}' # Count results .\/scripts\/puddle ls '#project' | jq 'length' # Filter locally .\/scripts\/puddle ls | jq '[.[] | select(.tags | contains(["important"]))]' ``` ## Exit Codes | Code | Meaning | |------|---------| | 0 | Success | | 1 | General error (missing token, invalid args, network) | | 2 | API error (4xx response) | | 3 | Not found \/ Invalid ID | ## Global Options ``` --token Override token (useful for scripts) --json Output errors as JSON (for programmatic parsing) --version Show version --help Show help ```