raindrop-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christian Catalan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,422 @@
+# raindrop-cli
+
+[![npm version](https://img.shields.io/npm/v/raindrop-cli)](https://npmjs.com/package/raindrop-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A fast, scriptable command-line interface for [Raindrop.io](https://raindrop.io) — the all-in-one bookmark manager.
+
+Built for power users, automation workflows, and AI agent integration.
+
+> **Disclaimer:** This is an unofficial, community-built tool and is not affiliated with or endorsed by Raindrop.io.
+
+## Features
+
+- **Full CRUD Operations** — Create, read, update, and delete bookmarks with ease
+- **Powerful Search** — Use Raindrop's full search syntax from the command line
+- **Batch Operations** — Update or delete multiple bookmarks at once via stdin piping
+- **Multiple Output Formats** — JSON, table, TSV, or plain text for any workflow
+- **AI-Friendly** — Structured output designed for LLM and agent consumption
+- **Scriptable** — Quiet mode, stdin support, and composable commands
+- **Collection Management** — Organize bookmarks with hierarchical collections
+- **Tag Operations** — Bulk rename, delete, and manage tags
+- **Fast** — Built with Bun for quick startup and execution
+
+## Requirements
+
+- Node.js 20+
+
+## Installation
+
+```bash
+npm install -g raindrop-cli
+```
+
+Or use without installing:
+```bash
+npx raindrop-cli --help
+```
+
+This installs `rd` as the primary command. An `rdcli` alias is also available if `rd` conflicts with another tool:
+
+- **Windows**: `rd` is a built-in command (remove directory)
+- **oh-my-zsh**: `rd` is aliased to `rmdir` — add `unalias rd` to your `~/.zshrc` or use `rdcli`
+
+## Quick Start
+
+### 1. Get Your API Token
+
+Get a test token from [Raindrop.io Integrations Settings](https://app.raindrop.io/settings/integrations).
+
+### 2. Authenticate
+
+```bash
+rd auth set-token
+# Paste your token when prompted
+```
+
+Or set via environment variable:
+
+```bash
+export RAINDROP_TOKEN=your-token-here
+```
+
+### 3. Start Using
+
+```bash
+# List your bookmarks
+rd list
+
+# Add a bookmark
+rd add https://example.com --tags "reading,tech"
+
+# Search your bookmarks
+rd search "typescript"
+
+# Get help
+rd --help
+```
+
+## Commands
+
+### Bookmarks
+
+The primary resource. Most bookmark commands have convenient shortcuts at the root level.
+
+```bash
+# List bookmarks
+rd list                                    # or: rd bookmarks list
+rd list --limit 50                         # limit results
+rd list --tag javascript                   # filter by tag
+rd list --type article                     # filter by type
+rd list --favorites                        # show only favorites
+rd list 12345                              # list from specific collection
+
+# Search
+rd search "typescript"                     # full-text search
+rd search "#javascript"                    # search by tag
+rd search "domain:github.com"              # search by domain
+rd search "type:article created:2024-01"   # combine filters
+
+# Show details
+rd show 12345                              # show bookmark by ID
+
+# Add bookmarks
+rd add https://example.com                 # basic add
+rd add https://example.com --title "My Title" --tags "dev,reading"
+rd add https://example.com --favorite      # add as favorite
+rd add https://example.com --collection 12345
+
+# Update bookmarks
+rd update 12345 --title "New Title"
+rd update 12345 --tags "new,tags"          # replace all tags
+rd update 12345 --favorite                 # mark as favorite
+rd update 12345 --favorite false           # remove favorite
+
+# Delete bookmarks
+rd delete 12345                            # prompts for confirmation
+rd delete 12345 --force                    # skip confirmation
+
+# Batch operations
+rd list -q | rd batch-update --favorite    # favorite all bookmarks
+rd list -q --tag old | rd batch-delete     # delete by tag
+rd batch-update --ids 123,456,789 --tags "archived"
+```
+
+### Collections
+
+Organize bookmarks into folders with optional nesting.
+
+```bash
+rd collections list                        # show collection tree
+rd collections list --flat                 # flat list with IDs
+rd collections show 12345                  # collection details
+rd collections add "My Collection"         # create collection
+rd collections add "Sub" --parent 12345    # create nested collection
+rd collections delete 12345 --force        # delete collection
+rd collections stats                       # show system collection counts
+```
+
+### Tags
+
+Manage tags across your bookmarks.
+
+```bash
+rd tags list                               # list all tags with counts
+rd tags list 12345                         # tags in specific collection
+rd tags rename "old-tag" "new-tag" -f      # rename (merges if exists)
+rd tags delete "unused-tag" -f             # remove tag from all bookmarks
+```
+
+### Favorites
+
+Quick access to your starred bookmarks.
+
+```bash
+rd favorites list                          # list all favorites
+rd favorites list 12345                    # favorites in collection
+rd favorites list -s "#javascript"         # filter favorites
+```
+
+### Highlights
+
+View your annotations and highlights.
+
+```bash
+rd highlights list                         # list all highlights
+rd highlights list -c 12345                # highlights in collection
+rd highlights show 12345                   # highlights for bookmark
+```
+
+### Filters
+
+Discover available filter values for search.
+
+```bash
+rd filters list                            # show types, tags, dates
+rd filters list 12345                      # filters for collection
+```
+
+### Trash
+
+Manage deleted bookmarks.
+
+```bash
+rd trash list                              # list trashed items
+rd trash empty --dry-run                   # preview deletion
+rd trash empty --force                     # permanently delete all
+```
+
+### Auth
+
+Manage authentication.
+
+```bash
+rd auth status                             # check auth status
+rd auth set-token                          # set new token (interactive)
+rd auth clear                              # remove stored token
+```
+
+## Output Formats
+
+Control output format for different use cases:
+
+```bash
+# Table (default for terminals)
+rd list
+
+# JSON (default when piped, great for jq)
+rd list --json
+rd list -f json | jq '.[].title'
+
+# TSV (spreadsheet-friendly)
+rd list -f tsv > bookmarks.tsv
+
+# Plain text (human-readable)
+rd list -f plain
+
+# Quiet mode (just IDs, for scripting)
+rd list -q
+rd list -q | xargs -I {} rd show {}
+```
+
+## Scripting Examples
+
+### Backup All Bookmarks
+
+```bash
+rd list --limit 50 --format json > backup.json
+```
+
+### Tag All Unsorted Bookmarks
+
+```bash
+rd list unsorted -q | rd batch-update --tags "needs-review"
+```
+
+### Delete Old Bookmarks
+
+```bash
+rd list --created 2020-01 -q | rd batch-delete
+```
+
+### Export to TSV for Spreadsheet
+
+```bash
+rd list --limit 100 -f tsv > bookmarks.tsv
+```
+
+### Find Broken Links
+
+```bash
+rd list --broken -f json | jq '.[] | {title, link}'
+```
+
+### Migrate Tags
+
+```bash
+rd tags rename "javascript" "js" -f
+```
+
+## Global Options
+
+```
+-V, --version            Output version number
+--format <format>        Output format: json, table, tsv, plain
+--json                   Shorthand for --format json
+-q, --quiet              Minimal output (just IDs)
+-v, --verbose            Show operational details
+-d, --debug              Show debug info
+--no-color               Disable colored output
+-t, --timeout <seconds>  Request timeout (default: 30, env: RDCLI_TIMEOUT)
+-h, --help               Display help
+```
+
+## Configuration
+
+### Token Storage
+
+Tokens can be provided via:
+
+1. **Environment variable** (takes precedence): `RAINDROP_TOKEN`
+2. **Config file**: `~/.config/raindrop-cli/config.json` (set via `rd auth set-token`)
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `RAINDROP_TOKEN` | API token (overrides config file) |
+| `RDCLI_TIMEOUT` | Request timeout in seconds (default: 30) |
+| `RDCLI_API_DELAY_MS` | Delay between API calls (milliseconds) |
+| `NO_COLOR` | Disable colored output |
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in development
+bun run dev -- list
+
+# Run tests
+bun run test              # unit tests
+bun run test:live         # live API tests (requires token)
+
+# Lint and format
+bun run lint
+bun run format
+
+# Type check
+bun run typecheck
+
+# Build
+bun run build
+
+# Run all checks
+bun run verify
+```
+
+### Verbose Commands
+
+Most commands have a `:verbose` variant with human-friendly output (e.g., `bun run test:verbose`). The defaults are optimized for AI agents with minimal output.
+
+### Live Tests in CI
+
+Live tests run against the real Raindrop.io API and require a token. In CI, maintainers and collaborators can trigger them by commenting `/run-live-tests` on a PR.
+
+> **Note:** Live tests only work on PRs from the same repository, not forks (secrets aren't available to forks for security).
+
+### Project Structure
+
+```
+src/
+├── index.ts           # CLI entry point
+├── commands/          # Command implementations
+├── output/            # Output formatters (json, table, tsv, plain)
+├── utils/             # Shared utilities
+└── types/             # TypeScript types
+```
+
+## Releasing
+
+For maintainers publishing a new version to npm.
+
+### Prerequisites
+
+- Push access to the repository
+- npm account with publish rights to `raindrop-cli`
+- Logged in to npm (`npm whoami` to verify)
+- ggshield installed and authenticated (`ggshield auth status`)
+
+### Release Process
+
+```bash
+# 1. Ensure you're on main with latest changes
+git checkout main
+git pull
+
+# 2. Update CHANGELOG.md
+# - Move items from "Unreleased" to new version section
+# - Set the release date (e.g., ## [0.2.0] - 2026-01-15)
+
+# 3. Commit the changelog
+git add CHANGELOG.md
+git commit -m "chore: update changelog for vX.Y.Z"
+
+# 4. Bump version (creates commit + git tag automatically)
+npm version patch  # or: minor, major
+# This updates package.json and creates a vX.Y.Z tag
+
+# 5. Dry run to verify package contents
+npm publish --dry-run --access public
+
+# 6. Publish to npm
+npm publish --access public
+
+# 7. Push commits and tags to GitHub
+git push && git push --tags
+
+# 8. Verify installation works
+npm info raindrop-cli
+npx raindrop-cli@latest --version
+```
+
+### What Happens During Publish
+
+The `prepublishOnly` script runs automatically before upload:
+
+1. **Verify** — runs tests, lint, typecheck, format
+2. **Build** — compiles to `dist/`
+3. **Secret scan** — ggshield scans source and `dist/` for leaked secrets
+4. **Package** — creates tarball with only: `dist/*`, `README.md`, `LICENSE`, `package.json`
+
+No need to run `bun run build` manually — it's all handled automatically.
+
+### Notes
+
+- **Immutable** — published versions cannot be changed, only deprecated
+- **Tags** — `npm version` creates the git tag; just remember to `git push --tags`
+- **Secrets** — publish will fail if ggshield detects secrets in the bundle
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+Quick start:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `bun run verify` to ensure tests pass
+5. Submit a pull request
+
+## License
+
+[MIT](LICENSE)
+
+## Links
+
+- [Raindrop.io](https://raindrop.io)
+- [Raindrop.io API Documentation](https://developer.raindrop.io)
+- [Changelog](CHANGELOG.md)
+- [Report Issues](https://github.com/crcatala/raindrop-cli-spike/issues)

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+import { client } from "@lasuillard/raindrop-client";
+declare const Raindrop: typeof client.Raindrop;
+type RaindropClient = InstanceType<typeof Raindrop>;
+export declare function getClient(): RaindropClient;
+export declare function resetClient(): void;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,MAAM,6BAA6B,CAAC;AAOhE,QAAA,MAAQ,QAAQ,wBAAW,CAAC;AAG5B,KAAK,cAAc,GAAG,YAAY,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIpD,wBAAgB,SAAS,IAAI,cAAc,CA2B1C;AAED,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/commands/auth.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createAuthCommand(): Command;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwEpC,wBAAgB,iBAAiB,IAAI,OAAO,CAuL3C"}

package/dist/commands/bookmarks.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createBookmarksCommand(): Command;
+//# sourceMappingURL=bookmarks.d.ts.map

package/dist/commands/bookmarks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookmarks.d.ts","sourceRoot":"","sources":["../../src/commands/bookmarks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8PpC,wBAAgB,sBAAsB,IAAI,OAAO,CAkvChD"}

package/dist/commands/collections.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createCollectionsCommand(): Command;
+//# sourceMappingURL=collections.d.ts.map

package/dist/commands/collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../../src/commands/collections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+FpC,wBAAgB,wBAAwB,IAAI,OAAO,CAkTlD"}

package/dist/commands/favorites.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createFavoritesCommand(): Command;
+//# sourceMappingURL=favorites.d.ts.map

package/dist/commands/favorites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"favorites.d.ts","sourceRoot":"","sources":["../../src/commands/favorites.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsEpC,wBAAgB,sBAAsB,IAAI,OAAO,CAwHhD"}

package/dist/commands/filters.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createFiltersCommand(): Command;
+//# sourceMappingURL=filters.d.ts.map

package/dist/commands/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/commands/filters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsFpC,wBAAgB,oBAAoB,IAAI,OAAO,CAmF9C"}

package/dist/commands/highlights.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createHighlightsCommand(): Command;
+//# sourceMappingURL=highlights.d.ts.map

package/dist/commands/highlights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlights.d.ts","sourceRoot":"","sources":["../../src/commands/highlights.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmDpC,wBAAgB,uBAAuB,IAAI,OAAO,CAiIjD"}

package/dist/commands/index.d.ts

@@ -0,0 +1,9 @@
+export { createAuthCommand } from "./auth.js";
+export { createBookmarksCommand } from "./bookmarks.js";
+export { createCollectionsCommand } from "./collections.js";
+export { createFavoritesCommand } from "./favorites.js";
+export { createHighlightsCommand } from "./highlights.js";
+export { createTagsCommand } from "./tags.js";
+export { createFiltersCommand } from "./filters.js";
+export { createTrashCommand } from "./trash.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/commands/tags.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createTagsCommand(): Command;
+//# sourceMappingURL=tags.d.ts.map

package/dist/commands/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../src/commands/tags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsCpC,wBAAgB,iBAAiB,IAAI,OAAO,CAwL3C"}

package/dist/commands/trash.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createTrashCommand(): Command;
+//# sourceMappingURL=trash.d.ts.map

package/dist/commands/trash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../../src/commands/trash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwDpC,wBAAgB,kBAAkB,IAAI,OAAO,CAoL5C"}

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+export interface StoredConfig {
+    token?: string;
+    defaultFormat?: "json" | "table" | "tsv";
+    defaultCollection?: number;
+}
+export interface ResolvedConfig {
+    token: string | null;
+    tokenSource: "env" | "config" | null;
+    defaultFormat: "json" | "table" | "tsv";
+    defaultCollection: number;
+}
+/**
+ * Get the stored token from config file (not env var).
+ */
+export declare function getStoredToken(): string | null;
+/**
+ * Store token in config file.
+ */
+export declare function setStoredToken(token: string): void;
+/**
+ * Clear token from config file.
+ */
+export declare function clearStoredToken(): void;
+/**
+ * Check if a token is configured (either env or config file).
+ */
+export declare function hasToken(): boolean;
+/**
+ * Get token source for display purposes.
+ */
+export declare function getTokenSource(): "env" | "config" | null;
+/**
+ * Get resolved config with precedence: env > config file.
+ */
+export declare function getConfig(): ResolvedConfig;
+/**
+ * Reset cached config (useful for testing or after token changes).
+ */
+export declare function resetConfig(): void;
+/**
+ * Get the config file path (for display purposes).
+ */
+export declare function getConfigFilePath(): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IACxC,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAwCD;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,KAAK,GAAG,QAAQ,GAAG,IAAI,CAQxD;AAID;;GAEG;AACH,wBAAgB,SAAS,IAAI,cAAc,CA2B1C;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}