buku

buku

buku in action!

### Introduction `buku` is a powerful bookmark manager and a personal textual mini-web. For those who prefer the GUI, `bukuserver` exposes a browsable front-end on a local web host server. See [bukuserver page](https://github.com/jarun/buku/tree/master/bukuserver#readme) for config and screenshots. When I started writing it, I couldn't find a flexible command-line solution with a private, portable, merge-able database along with seamless GUI integration. Hence, `buku`. `buku` can import bookmarks from browser(s) or fetch the title, tags and description of a URL from the web. Use your favourite editor to add, compose and update bookmarks. Search bookmarks instantly with multiple search options, including regex and a deep scan mode (handy with URLs). It can look up broken links on the Wayback Machine. There's an Easter Egg to revisit random bookmarks. There's no tracking, hidden history, obsolete records, usage analytics or homing. To get started right away, jump to the [Quickstart](#quickstart) section. `buku` has one of the best documentation around. The man page comes with examples. For internal details, please refer to the [operational notes](https://github.com/jarun/buku/wiki/Operational-notes). `buku` is a library too! There are several related projects, including a browser plug-in. ### Table of Contents - [Features](#features) - [Installation](#installation) - [Dependencies](#dependencies) - [From a package manager](#from-a-package-manager) - [Release packages](#release-packages) - [From source](#from-source) - [Running standalone](#running-standalone) - [Shell completion](#shell-completion) - [Usage](#usage) - [Command-line options](#command-line-options) - [Colors](#colors) - [Quickstart](#quickstart) - [Examples](#examples) - [Automation](#automation) - [Troubleshooting](#troubleshooting) - [Editor integration](#editor-integration) - [Collaborators](#collaborators) - [Contributions](#contributions) - [Related projects](#related-projects) - [In the Press](#in-the-press) ### Features - Store bookmarks with auto-fetched title, tags and description - Auto-import from Firefox, Google Chrome, Chromium, Vivaldi, Vivaldi Beta (Internal), Brave, and MS Edge - Open bookmarks and search results in browser - Browse cached page from the Wayback Machine - Text editor integration - Lightweight, clean interface, custom colors - Powerful search options (regex, substring...) - Continuous search with on the fly mode switch - Portable, merge-able database to sync between systems - Import/export bookmarks from/to HTML, XBEL, Markdown, RSS/Atom or Orgfile - Smart tag management using redirection (>>, >, <<) - Multi-threaded full DB refresh - Manual encryption support - Shell completion scripts, man page with handy examples - Privacy-aware (no unconfirmed user data collection) - Can be used as a Python library ([_API documentation_](https://buku.readthedocs.io/en/latest/?badge=latest)) - Has a compation Web-application ([Bukuserver](https://github.com/jarun/buku/wiki/Bukuserver-%28WebUI%29)) with an HTTP-based API (for personal use only) ### Installation #### Dependencies | Feature | Dependency | | --- | --- | | Lang, SQLite | Python 3.10+ | | HTTPS | certifi, urllib3 | | Encryption | cryptography | | HTML | beautifulsoup4, html5lib | To copy URL to clipboard `buku` uses `xsel` (or `xclip`) on Linux, `pbcopy` (default installed) on OS X, `clip` (default installed) on Windows, `termux-clipboard` on Termux (terminal emulation for Android), `wl-copy` on Wayland. If X11 is missing, GNU Screen or tmux copy-paste buffers are recognized. #### From a package manager To install buku with all its dependencies from PyPI, run: # pip3 install buku You can also install `buku` from your package manager. If the version available is dated try an alternative installation method. Packaging status (expand)

Unlisted packagers:

● PyPI (pip3 install buku)
● Termux (pip3 install buku)

#### Release packages Auto-generated packages (with only the cli component) for Arch Linux, CentOS, Debian, Fedora, openSUSE Leap and Ubuntu are available with the [latest stable release](https://github.com/jarun/buku/releases/latest). NOTE: CentOS may not have the python3-beautifulsoup4 package in the repos. Install it using pip3. #### From source If you have git installed, clone this repository. Otherwise download the [latest stable release](https://github.com/jarun/buku/releases/latest) or [development version](https://github.com/jarun/buku/archive/master.zip) (*risky*). Install the dependencies. For example, on Ubuntu: $ apt-get install ca-certificates python3-urllib3 python3-cryptography python3-bs4 Install the cli component to default location (`/usr/local`): $ sudo make install To remove, run: $ sudo make uninstall `PREFIX` is supported, in case you want to install to a different location. #### Running standalone `buku` is a standalone utility. From the containing directory, run: $ chmod +x buku.py $ ./buku.py ### Shell completion Shell completion scripts for Bash, Fish and Zsh can be found in respective subdirectories of [auto-completion/](https://github.com/jarun/buku/blob/master/auto-completion). Please refer to your shell's manual for installation instructions. ### Usage #### Command-line options ``` … ``` #### Colors `buku` supports custom colors. Visit the wiki page on how to [customize colors](https://github.com/jarun/buku/wiki/Customize-colors) for more details. ### Quickstart 1. Export `VISUAL` or `EDITOR` to point to your favourite editor. Note that `VISUAL` takes precedence over `EDITOR`. 2. Create a sweeter shortcut with some convenience. alias b='buku --suggest' 3. Auto-import bookmarks from your browser(s). Please quit the relevant browsers beforehand to ensure the databases are not locked. b --ai For Chrome, Chromium, Vivaldi (including Internal), and Brave, auto-import reads both plaintext `Bookmarks` and `AccountBookmarks` files when available. Encrypted bookmark files are not supported; export bookmarks as HTML from the browser and import the exported file with `buku -i bookmarks.html` instead. 4. Manually add a bookmark (for hands-on). b -w 5. List your bookmarks with DB index. b -p 6. For GUI and browser integration (or to sync bookmarks with your favourite bookmark management service) refer to the wiki page on [System integration](https://github.com/jarun/buku/wiki/System-integration). 7. Quick (bash/zsh) commands to fuzzy search with fzf and open the selection in Firefox: firefox $(buku -p -f 10 | fzf) firefox $(buku -p -f 40 | fzf | cut -f1) POSIX script to show a preview of the bookmark as well: ```sh #!/usr/bin/env sh url=$(buku -p -f4 | fzf -m --reverse --preview "buku -p {1}" --preview-window=wrap | cut -f2) if [ -n "$url" ]; then echo "$url" | xargs firefox fi ``` ### Examples 1. **Edit and add** a bookmark from editor: $ buku -w $ buku -w 'gedit -w' $ buku -w 'macvim -f' -a https://ddg.gg search engine, privacy The first command picks editor from the environment variable `EDITOR`. The second command opens gedit in blocking mode. The third command opens macvim with option -f and the URL and tags populated in template. 2. **Add** a simple bookmark: $ buku --nostdin -a https://github.com/ 2648. GitHub: Let’s build from here · GitHub > https://github.com/ + GitHub is where over 94 million developers shape the future of software, together. Contribute to the open source community, manage your Git repositories, review code like a pro, track bugs and features, power your CI/CD and DevOps workflows, and secure code before you commit it. $ buku --nostdin -a https://github.com/ [ERROR] URL [https://github.com/] already exists at index 2648 `>`: URL, `+`: comment, `#`: tags Title, description and tags will be fetched from site. Buku only stores unique URLs and will raise error if the URL already present in the database: 3. **Add** a bookmark with **tags** `search engine` and `privacy`, **comment** `Search engine with perks`, **fetch page title** from the web: $ buku -a https://ddg.gg search engine, privacy -c Search engine with perks 336. DuckDuckGo > https://ddg.gg + Alternative search engine with perks # privacy,search engine where, `>`: URL, `+`: comment, `#`: tags 4. **Add** a bookmark with tags `search engine` & `privacy` and **immutable custom title** `DDG`: $ buku -a https://ddg.gg search engine, privacy --title 'DDG' --immutable 1 336. DDG (L) > https://ddg.gg # privacy,search engine Note that URL must precede tags. 5. **Add** a bookmark **without a title** (works for update too): $ buku -a https://ddg.gg search engine, privacy --title 6. **Edit and update** a bookmark from editor: $ buku -w 15012014 This will open the existing bookmark's details in the editor for modifications. Environment variable `EDITOR` must be set. 7. **Update** existing bookmark at index 15012014 with new URL, tags and comments, fetch title from the web: $ buku -u 15012014 --url http://ddg.gg/ --tag web search, utilities -c Private search engine 8. **Fetch and update only title** for bookmark at 15012014: $ buku -u 15012014 9. **Update only comment** for bookmark at 15012014: $ buku -u 15012014 -c this is a new comment Applies to --url, --title and --tag too. 10. **Export** bookmarks tagged `tag 1` or `tag 2` to HTML, XBEL, Markdown, Orgfile or a new database: $ buku -e bookmarks.html --stag tag 1, tag 2 $ buku -e bookmarks.xbel --stag tag 1, tag 2 $ buku -e bookmarks.md --stag tag 1, tag 2 $ buku -e bookmarks.org --stag tag 1, tag 2 $ buku -e bookmarks.db --stag tag 1, tag 2 All bookmarks are exported if search is not opted. 11. **Import** bookmarks from HTML, XBEL, Markdown or Orgfile: $ buku -i bookmarks.html $ buku -i bookmarks.xbel $ buku -i bookmarks.md $ buku -i bookmarks.org $ buku -i bookmarks.db 12. **Delete only comment** for bookmark at 15012014: $ buku -u 15012014 -c Applies to --title and --tag too. URL cannot be deleted without deleting the bookmark. 13. **Update** or refresh **full DB** with page titles from the web: $ buku -u $ buku -u --tacit (show only failures and exceptions) This operation can update the title or description fields of non-immutable bookmarks by parsing the fetched page. Fields are updated only if the fetched fields are non-empty. Tags remain untouched. 14. **Delete** bookmark at index 15012014: $ buku -d 15012014 Index 15012020 moved to 15012014 The last index is moved to the deleted index to keep the DB compact. Add `--tacit` to delete without confirmation. 15. **Delete all** bookmarks: $ buku -d 16. **Delete** a **range or list** of bookmarks: $ buku -d 100-200 $ buku -d 100 15 200 17. **Search** bookmarks for **ANY** of the keywords `kernel` and `debugging` i