https://github.com/davep/braindrop
A terminal-based client for raindrop.io
https://github.com/davep/braindrop
bookmarking bookmarking-app bookmarks bookmarks-manager chui python python3 raindrop raindrop-api raindrop-io terminal terminal-based textual tui
Last synced: 2 months ago
JSON representation
A terminal-based client for raindrop.io
- Host: GitHub
- URL: https://github.com/davep/braindrop
- Owner: davep
- License: gpl-3.0
- Created: 2024-11-28T09:17:39.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-02-23T21:28:18.000Z (4 months ago)
- Last Synced: 2025-04-02T00:37:11.521Z (2 months ago)
- Topics: bookmarking, bookmarking-app, bookmarks, bookmarks-manager, chui, python, python3, raindrop, raindrop-api, raindrop-io, terminal, terminal-based, textual, tui
- Language: Python
- Homepage: https://pypi.org/project/braindrop/
- Size: 3.26 MB
- Stars: 43
- Watchers: 2
- Forks: 2
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Braindrop
## Introduction
Braindrop is a terminal-based client application for the [raindrop.io
bookmarking service](https://raindrop.io/). It provides the ability to
manage and search your bookmarks in the terminal.
Braindrop is and generally always will be fairly opinionated about the
"best" way to make use of Raindrop (AKA how I like to use it); but where
possible I want to keep it quite general so it will be useful to anyone.
> [!NOTE]
> Braindrop isn't designed as a thin client for the Raindrop API; it isn't a
> terminal-based browser that does all the work on the server. It is
> designed to download your data if it looks like it's newer on the server,
> and then work locally, sending updates back to the server.
>
> If you have a *huge* Raindrop collection then this might not be the tool
> for you.
## Installing
### pipx
The package can be installed using [`pipx`](https://pypa.github.io/pipx/):
```sh
$ pipx install braindrop
```
Once installed run the `braindrop` command.
### Homebrew
The package is available via Homebrew. Use the following commands to install:
```sh
$ brew tap davep/homebrew
$ brew install braindrop
```
Once installed run the `braindrop` command.
## Getting started
Braindrop only works if you have a [raindrop.io](https://raindrop.io/)
account; there is a perfectly usable free tier. If you don't have an
account, go get one first.
To use Braindrop you will need an API access token. You can generate one in
your account settings, under `Integrations`. In `Integrations`:
- Look for the `For Developers` section
- Click on `Create new app`
- Enter a name for the new app (call it `Braindrop` for example, so you know
what you're using it for).
- Accept the API use terms and guidelines and press `Create`
- Click on the freshly-created application in the list
- Near the bottom of the dialog that appears, click on `Create test token`
and say `OK`.
- Copy the test token to your clipboard (or don't worry if you misplace it,
you can always come back here to get it again).
Having done the above, when you run up Braindrop the first time it will ask
for this token:
Paste the token into the input field and select `Connect`. Braindrop will
then download your data and you will be good to go.
*NOTE: if it's your preference, you can set the token in an environment
variable called `BRAINDROP_API_TOKEN`.*
## Using Braindrop
The best way to get to know Braindrop is to read the help screen, once in the
main application you can see this by pressing F1.
## File locations
Braindrop stores files in a `braindrop` directory within both
[`$XDG_DATA_HOME` and
`$XDG_CONFIG_HOME`](https://specifications.freedesktop.org/basedir-spec/latest/).
If you wish to fully remove anything to do with Braindrop you will need to
remove those directories too.
Expanding for the common locations, the files normally created are:
- `~/.config/braindrop/configuration.json` -- The configuration file.
- `~/.local/share/braindrop/.token` -- The file that hold your API token.
- `~/.local/share/braindrop/raindrops.json` -- The locally-held Raindrop data.
## Getting help
If you need help, or have any ideas, please feel free to [raise an
issue](https://github.com/davep/braindrop/issues) or [start a
discussion](https://github.com/davep/braindrop/discussions).
## TODO
See [the TODO tag in
issues](https://github.com/davep/braindrop/issues?q=is%3Aissue+is%3Aopen+label%3ATODO)
to see what I'm planning.
[//]: # (README.md ends here)