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.
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-contextexposes machine-readable command metadata- raw API escape hatch with
raindrop api request
Requires Node.js >=24.
npm install -g @mocito/raindrop-cli
pnpm add -g @mocito/raindrop-cli
bun add -g @mocito/raindrop-cliWith Homebrew:
brew tap jvm/tap
brew install raindrop-cliRun without installing:
npx @mocito/raindrop-cli --help
pnpm dlx @mocito/raindrop-cli --help
bunx @mocito/raindrop-cli --helpAs a project dev dependency:
npm install -D @mocito/raindrop-cli
pnpm add -D @mocito/raindrop-cli
bun add -d @mocito/raindrop-cliprintf '%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.csvFor local use, store a token securely:
printf '%s' "$RAINDROP_ACCESS_TOKEN" | raindrop auth login --token-stdin
raindrop auth statusFor CI and ephemeral environments, avoid writing credentials to disk and pass the token as an environment variable:
RAINDROP_ACCESS_TOKEN=... raindrop user getSee docs/auth.md for token setup, credential paths, precedence, and OAuth notes.
# 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 doctorMore examples are in docs/examples.md.
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.
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.
This repository publishes a skills.sh/Agent Skills-compatible skill at skills/raindrop-cli/SKILL.md:
npx skills add jvm/raindrop-cli --skill raindrop-cliValidate the skill locally with:
pnpm run skill:validate- Authentication
- Command reference
- Examples
- Output and error contract
- Troubleshooting
- Design notes
- Agent context schema
- Security policy
- Contributing
- Changelog
This repository uses pnpm.
pnpm install
pnpm validate
pnpm build
pnpm test
pnpm test:watch
pnpm lint
pnpm format
pnpm format:check
pnpm typecheck
pnpm verify-packGenerated command docs and specs come from spec/commands.yaml. Run pnpm codegen after editing that file.
Tests must use mocks or local helpers and must not require live Raindrop credentials.
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.
MIT. See LICENSE.