Raindrop CLI

Agent-friendly and script-friendly CLI for Raindrop.io. The binary is raindrop, stdout is JSON by default, and CLI-rendered errors are structured JSON on stderr.

Why this CLI?

raindrop is designed for automation first:

• JSON stdout by default for reliable scripting and agent use
• structured JSON errors on stderr with stable exit codes
• bounded list operations; no hidden full-account pagination
• destructive operations require --force
• credentials and authorization headers are redacted from debug paths
• agent-context exposes machine-readable command metadata
• raw API escape hatch with raindrop api request

Installation

Requires Node.js >=20.11.

npm install -g @mocito/raindrop-cli
pnpm add -g @mocito/raindrop-cli
bun add -g @mocito/raindrop-cli

With Homebrew:

brew tap jvm/tap
brew install raindrop-cli

Run without installing:

npx @mocito/raindrop-cli --help
pnpm dlx @mocito/raindrop-cli --help
bunx @mocito/raindrop-cli --help

As a project dev dependency:

npm install -D @mocito/raindrop-cli
pnpm add -D @mocito/raindrop-cli
bun add -d @mocito/raindrop-cli

Quickstart

printf '%s' "$RAINDROP_ACCESS_TOKEN" | raindrop auth login --token-stdin
raindrop user get
raindrop bookmark add https://developer.raindrop.io --tag api --tag docs
raindrop bookmark list --collection 0 --limit 50
raindrop collection list --human
raindrop export bookmarks 0 csv --output bookmarks.csv

Authentication

For local use, store a token securely:

printf '%s' "$RAINDROP_ACCESS_TOKEN" | raindrop auth login --token-stdin
raindrop auth status

For CI and ephemeral environments, avoid writing credentials to disk and pass the token as an environment variable:

RAINDROP_ACCESS_TOKEN=... raindrop user get

See docs/auth.md for token setup, credential paths, precedence, and OAuth notes.

Common workflows

# Search bookmarks and print titles with jq
raindrop bookmark search "tag:api" --collection 0 --limit 10 | jq -r '.items[].title'

# Add a bookmark to a collection
raindrop bookmark add https://example.com --collection 42 --tag reference

# Export all non-trash bookmarks to CSV
raindrop export bookmarks 0 csv --output bookmarks.csv

# Diagnose local config, auth, and API connectivity
raindrop doctor

More examples are in docs/examples.md.

Install telemetry

raindrop sends a best-effort install/update ping once per installed version. Disable it with RAINDROP_TELEMETRY=0. Telemetry is also disabled automatically when CI=true or GITHUB_ACTIONS=true.

Output contract

Success output is JSON by default. Human output is opt-in with --human where available.

Errors are structured JSON on stderr:

{
  "error": {
    "code": "auth_missing",
    "message": "No Raindrop.io access token configured",
    "hint": "Run: raindrop auth login --token-stdin, or set RAINDROP_ACCESS_TOKEN",
    "status": 401
  }
}

See docs/output.md for the full stdout/stderr contract and stable exit codes.

Agent skill

This repository publishes a skills.sh/Agent Skills-compatible skill at skills/raindrop-cli/SKILL.md:

npx skills add jvm/raindrop-cli --skill raindrop-cli

Validate the skill locally with:

pnpm run skill:validate

Documentation

• Authentication
• Command reference
• Examples
• Output and error contract
• Troubleshooting
• Design notes
• Agent context schema
• Security policy
• Contributing
• Changelog

Development

This repository uses pnpm.

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm format
pnpm typecheck
pnpm verify-pack

Generated command docs and specs come from spec/commands.yaml:

pnpm codegen

Tests must use mocks or local helpers and must not require live Raindrop credentials.

Security

Never include live Raindrop access tokens, refresh tokens, client secrets, or Authorization headers in issues, logs, tests, or snapshots. Report vulnerabilities privately as described in SECURITY.md.

License

MIT. See LICENSE.