commands.md

Command Reference

Generated from spec/commands.yaml on 2026-06-15.

Command names below use the actual shell syntax. The source command IDs in spec/commands.yaml use dots, for example bookmark.add maps to raindrop bookmark add.

Global flags

These flags are accepted by the top-level CLI and apply to most commands:

Flag	Description
--json	Force JSON output. This is the default stdout contract.
--human	Print human-readable output where available.
--profile <name>	Use a named profile for this invocation.
--base-url <url>	Override the API base URL, mainly for tests and mocks.
--debug	Include debug details with secret redaction. Do not paste debug output into public issues without reviewing it.
--no-color	Disable color in human output.
--help	Show CLI or command help.
--version	Show the installed version.

Commands

Command	Summary
raindrop auth login	Store a token or OAuth credentials for a profile
raindrop auth status	Show authentication status and token source
raindrop auth logout	Remove stored credentials for a profile (requires --force)
raindrop auth refresh	Manually refresh OAuth token
raindrop config path	Print config and credentials file paths
raindrop config list	List all config values with their source (env, profile, file, default)
raindrop config get	Get a single config value
raindrop config set	Set a config value
raindrop config unset	Remove a config value
raindrop profile list	List all named profiles
raindrop profile get	Show profile defaults and auth status
raindrop profile save	Save or update a named profile with non-secret defaults
raindrop profile use	Set the active profile
raindrop profile delete	Delete a named profile (requires --force)
raindrop user get	Get authenticated user
raindrop user public	Get a public user by name
raindrop user stats	Get authenticated user statistics
raindrop user update	Update authenticated user
raindrop collection list	List root collections
raindrop collection children	List child (nested) collections
raindrop collection tree	Show full collection tree (roots + children)
raindrop collection get	Get a single collection by ID
raindrop collection create	Create a new collection
raindrop collection update	Update a collection
raindrop collection delete	Delete a collection (requires --force)
raindrop collection delete-many	Delete multiple collections (requires --force)
raindrop collection reorder	Reorder collections by sort key
raindrop collection expand	Expand all collections in the sidebar
raindrop collection collapse	Collapse all collections in the sidebar
raindrop collection merge	Merge collections into a target
raindrop collection clean-empty	Remove empty collections (requires --force)
raindrop collection empty-trash	Permanently empty Trash (requires --force)
raindrop collection cover upload	Upload a cover image for a collection
raindrop collection cover search	Search for collection covers by text
raindrop collection cover featured	List featured collection covers
raindrop collection sharing list	List collaborators for a collection
raindrop collection sharing invite	Invite users to a collection
raindrop collection sharing update	Update a collaborator's role
raindrop collection sharing remove	Remove a collaborator (requires --force)
raindrop collection sharing leave	Leave a shared collection (requires --force)
raindrop collection sharing join	Join a shared collection with an invite token
raindrop bookmark list	List one bounded page of bookmarks
raindrop bookmark search	Search bookmarks with a query
raindrop bookmark get	Get a single bookmark by ID
raindrop bookmark add	Add a URL bookmark with retry-safe duplicate detection
raindrop bookmark create	Create a bookmark with full JSON body
raindrop bookmark update	Update a bookmark
raindrop bookmark delete	Delete a bookmark (requires --force)
raindrop bookmark upload-file	Upload a file as a bookmark
raindrop bookmark upload-cover	Upload a cover image for a bookmark
raindrop bookmark download	Download a bookmark cache or cover
raindrop bookmark suggest	Get bookmark suggestions by ID or URL
raindrop bookmark bulk-create	Create up to 100 bookmarks at once
raindrop bookmark bulk-update	Update multiple bookmarks in a collection
raindrop bookmark bulk-delete	Delete multiple bookmarks (requires --force)
raindrop tag list	List tags for a collection
raindrop tag rename	Rename a tag
raindrop tag merge	Merge multiple tags into one
raindrop tag delete	Delete tags (requires --force)
raindrop filter get	Get filter counts for a collection
raindrop highlight list	List highlights (all or by collection)
raindrop highlight add	Add a highlight to a bookmark
raindrop highlight update	Update a highlight on a bookmark
raindrop highlight delete	Delete a highlight from a bookmark (requires --force)
raindrop import parse-url	Parse a URL for bookmark metadata
raindrop import exists	Check if URLs already exist as bookmarks
raindrop import parse-file	Parse an HTML bookmark import file
raindrop export bookmarks	Export bookmarks as csv, html, or zip
raindrop backup list	List available backups
raindrop backup generate	Trigger backup generation, optionally wait for completion
raindrop backup download	Download a backup file
raindrop jobs list	List local async job ledger entries
raindrop jobs get	Get a specific job entry
raindrop jobs prune	Remove old job entries
raindrop feedback	Record local feedback
raindrop feedback list	List recorded feedback entries
raindrop feedback clear	Clear all feedback entries (requires --force)
raindrop feedback send	Send feedback to an endpoint
raindrop doctor	Run structured config/auth/network/path diagnostics
raindrop agent-context	Print machine-readable CLI context for agents
raindrop api request	Raw API escape hatch
raindrop completion	Generate shell completion script
raindrop update	Print update instructions

raindrop auth login

Store a token or OAuth credentials for a profile

Examples:

printf '%s' "$RAINDROP_ACCESS_TOKEN" | raindrop auth login --token-stdin
raindrop auth login --token <test-token>
raindrop auth login --client-id <id> --client-secret <secret> --redirect-uri http://127.0.0.1:53682/callback

raindrop auth status

Show authentication status and token source

Examples:

raindrop auth status

raindrop auth logout

Remove stored credentials for a profile (requires --force)

Examples:

raindrop auth logout --force

raindrop auth refresh

Manually refresh OAuth token

Examples:

raindrop auth refresh

raindrop config path

Print config and credentials file paths

Examples:

raindrop config path

raindrop config list

List all config values with their source (env, profile, file, default)

Examples:

raindrop config list

raindrop config get

Get a single config value

Examples:

raindrop config get output

raindrop config set

Set a config value

Examples:

raindrop config set output json

raindrop config unset

Remove a config value

Examples:

raindrop config unset default_collection

raindrop profile list

List all named profiles

Examples:

raindrop profile list

raindrop profile get

Show profile defaults and auth status

Examples:

raindrop profile get work

raindrop profile save

Save or update a named profile with non-secret defaults

Examples:

raindrop profile save work --default-collection 123456 --output json

raindrop profile use

Set the active profile

Examples:

raindrop profile use work

raindrop profile delete

Delete a named profile (requires --force)

Examples:

raindrop profile delete work --force

raindrop user get

Get authenticated user

Examples:

raindrop user get

raindrop user public

Get a public user by name

Examples:

raindrop user public <name>

raindrop user stats

Get authenticated user statistics

Examples:

raindrop user stats

raindrop user update

Update authenticated user

Examples:

raindrop user update -d '{"fullName":"New Name"}'

raindrop collection list

List root collections

Examples:

raindrop collection list --human

raindrop collection children

List child (nested) collections

Examples:

raindrop collection children

raindrop collection tree

Show full collection tree (roots + children)

Examples:

raindrop collection tree --human

raindrop collection get

Get a single collection by ID

Examples:

raindrop collection get 123

raindrop collection create

Create a new collection

Examples:

raindrop collection create --title "Reading List" --view list

raindrop collection update

Update a collection

Examples:

raindrop collection update 123 --title "New Title" --public=false

raindrop collection delete

Delete a collection (requires --force)

Examples:

raindrop collection delete 123 --force

raindrop collection delete-many

Delete multiple collections (requires --force)

Examples:

raindrop collection delete-many 1 2 3 --force

raindrop collection reorder

Reorder collections by sort key

Examples:

raindrop collection reorder --sort title

raindrop collection expand

Expand all collections in the sidebar

Examples:

raindrop collection expand --all

raindrop collection collapse

Collapse all collections in the sidebar

Examples:

raindrop collection collapse --all

raindrop collection merge

Merge collections into a target

Examples:

raindrop collection merge --to 123 456 789

raindrop collection clean-empty

Remove empty collections (requires --force)

Examples:

raindrop collection clean-empty --force

raindrop collection empty-trash

Permanently empty Trash (requires --force)

Examples:

raindrop collection empty-trash --force

raindrop collection cover upload

Upload a cover image for a collection

Examples:

raindrop collection cover upload 123 --file cover.png

raindrop collection cover search

Search for collection covers by text

Examples:

raindrop collection cover search "nature"

raindrop collection cover featured

List featured collection covers

Examples:

raindrop collection cover featured

raindrop collection sharing list

List collaborators for a collection

Examples:

raindrop collection sharing list 123

raindrop collection sharing invite

Invite users to a collection

Examples:

raindrop collection sharing invite 123 --role viewer --email a@example.com

raindrop collection sharing update

Update a collaborator's role

Examples:

raindrop collection sharing update 123 456 --role member

raindrop collection sharing remove

Remove a collaborator (requires --force)

Examples:

raindrop collection sharing remove 123 456 --force

raindrop collection sharing leave

Leave a shared collection (requires --force)

Examples:

raindrop collection sharing leave 123 --force

raindrop collection sharing join

Join a shared collection with an invite token

Examples:

raindrop collection sharing join 123 --token <invite-token>

raindrop bookmark list

List one bounded page of bookmarks

Examples:

raindrop bookmark list --collection 0 --limit 50
raindrop bookmark list --collection 0 --sort -created --search "tag:api"

raindrop bookmark search

Search bookmarks with a query

Examples:

raindrop bookmark search "tag:api type:article" --collection 0

raindrop bookmark get

Get a single bookmark by ID

Examples:

raindrop bookmark get 123

raindrop bookmark add

Add a URL bookmark with retry-safe duplicate detection

Examples:

raindrop bookmark add https://developer.raindrop.io --tag api --tag docs
raindrop bookmark add https://example.com --collection 42 --important
raindrop bookmark add https://example.com --allow-duplicate

raindrop bookmark create

Create a bookmark with full JSON body

Examples:

raindrop bookmark create -d '{"link":"https://example.com","title":"Example"}'

raindrop bookmark update

Update a bookmark

Examples:

raindrop bookmark update 123 --title "New Title" --tag archived

raindrop bookmark delete

Delete a bookmark (requires --force)

Examples:

raindrop bookmark delete 123 --force

raindrop bookmark upload-file

Upload a file as a bookmark

Examples:

raindrop bookmark upload-file --file ./paper.pdf --collection 42

raindrop bookmark upload-cover

Upload a cover image for a bookmark

Examples:

raindrop bookmark upload-cover 123 --file cover.png

raindrop bookmark download

Download a bookmark cache or cover

Examples:

raindrop bookmark download 123 --variant cache --output cached.html

raindrop bookmark suggest

Get bookmark suggestions by ID or URL

Examples:

raindrop bookmark suggest 123
raindrop bookmark suggest --url https://example.com

raindrop bookmark bulk-create

Create up to 100 bookmarks at once

Examples:

raindrop bookmark bulk-create -d @bookmarks.json

raindrop bookmark bulk-update

Update multiple bookmarks in a collection

Examples:

raindrop bookmark bulk-update --collection 42 --ids 1,2,3 --tag archived

raindrop bookmark bulk-delete

Delete multiple bookmarks (requires --force)

Examples:

raindrop bookmark bulk-delete --collection 42 --ids 1,2,3 --force

raindrop tag list

List tags for a collection

Examples:

raindrop tag list --collection 0

raindrop tag rename

Rename a tag

Examples:

raindrop tag rename old-name new-name --collection 0

raindrop tag merge

Merge multiple tags into one

Examples:

raindrop tag merge new-name old-a old-b --collection 0

raindrop tag delete

Delete tags (requires --force)

Examples:

raindrop tag delete tag-a tag-b --collection 0 --force

raindrop filter get

Get filter counts for a collection

Examples:

raindrop filter get --collection 0

raindrop highlight list

List highlights (all or by collection)

Examples:

raindrop highlight list --page 0 --limit 50
raindrop highlight list --collection 42

raindrop highlight add

Add a highlight to a bookmark

Examples:

raindrop highlight add 123 --text "quote" --color yellow --note "important"

raindrop highlight update

Update a highlight on a bookmark

Examples:

raindrop highlight update 123 abc --note "new note" --color green

raindrop highlight delete

Delete a highlight from a bookmark (requires --force)

Examples:

raindrop highlight delete 123 abc --force

raindrop import parse-url

Parse a URL for bookmark metadata

Examples:

raindrop import parse-url https://example.com

raindrop import exists

Check if URLs already exist as bookmarks

Examples:

raindrop import exists https://a.example https://b.example

raindrop import parse-file

Parse an HTML bookmark import file

Examples:

raindrop import parse-file --file bookmarks.html

raindrop export bookmarks

Export bookmarks as csv, html, or zip

Examples:

raindrop export bookmarks 0 csv --output bookmarks.csv
raindrop export bookmarks 0 html --deliver=stdout

raindrop backup list

List available backups

Examples:

raindrop backup list

raindrop backup generate

Trigger backup generation, optionally wait for completion

Examples:

raindrop backup generate
raindrop backup generate --wait --timeout 10m

raindrop backup download

Download a backup file

Examples:

raindrop backup download <id> csv --output backup.csv

raindrop jobs list

List local async job ledger entries

Examples:

raindrop jobs list

raindrop jobs get

Get a specific job entry

Examples:

raindrop jobs get <job-id>

raindrop jobs prune

Remove old job entries

Examples:

raindrop jobs prune --older-than 30d

raindrop feedback

Record local feedback

Examples:

raindrop feedback "bookmark add returned wrong existing item"

raindrop feedback list

List recorded feedback entries

Examples:

raindrop feedback list

raindrop feedback clear

Clear all feedback entries (requires --force)

Examples:

raindrop feedback clear --force

raindrop feedback send

Send feedback to an endpoint

Examples:

raindrop feedback send --endpoint https://example.com/api/feedback

raindrop doctor

Run structured config/auth/network/path diagnostics

Examples:

raindrop doctor
raindrop doctor --fix-permissions

raindrop agent-context

Print machine-readable CLI context for agents

Examples:

raindrop agent-context
raindrop agent-context --command bookmark.add

raindrop api request

Raw API escape hatch

Examples:

raindrop api request GET /user
raindrop api request PUT /raindrop/123 -d '{"important":true}'

raindrop completion

Generate shell completion script

Examples:

raindrop completion bash
raindrop completion zsh

raindrop update

Print update instructions

Examples:

raindrop update