pjht/buku

History

Arun Prakash Jana dae70f8309 A shorter tagline		2018-05-11 08:00:40 +05:30
..
buku.rst	Sphinx (#200 )	2017-09-09 09:10:05 +05:30
conf.py	Prepare for release v3.6	2018-01-01 20:00:01 +05:30
index.rst	A shorter tagline	2018-05-11 08:00:40 +05:30
README.md	Sphinx readme md (#202 )	2017-09-09 22:42:48 +05:30

README.md

Buku

Buku in action!

Introduction

buku is a powerful bookmark manager written in Python3 and SQLite3. When I started writing it, I couldn't find a flexible cmdline solution with a private, portable, merge-able database along with seamless GUI integration. Hence, Buku (after my son's nickname, meaning close to the heart in my language).

buku fetches the title of a bookmarked url and stores it along with any user-provided comments and tags. You can use your favourite editor to compose and update bookmarks. With multiple search options, including regex and a deep scan mode (particularly for URLs), it can find any bookmark instantly. Multiple search results can be opened in the browser at once. There's an Easter egg to revisit random forgotten bookmarks too!

For GUI and browser integration (or to sync bookmarks with your favourite bookmark management service), refer to the wiki page on System integration. If you prefer the terminal, the shell completion scripts can be handy.

bukuserver exposes a browsable frontend on a local webhost server.

We have one of the best documentation around. You can start with the Examples. Buku is too busy to track you - no hidden history, obsolete records, usage analytics or homing. For more details, please refer to the wiki page on operational notes.

There are several projects based on buku, including a browser plug-in.

Missing a feature? There's a rolling ToDo List with identified tasks. Contributions are welcome! Please follow the PR guidelines.

Love smart and efficient terminal utilities? Explore my repositories. Buy me a cup of coffee if they help you.

Features
Installation
Shell completion
Usage
- Cmdline options
- Colors
Examples
Troubleshooting
- Editor integration
Collaborators
Related projects
In the Press

Features

Lightweight, clean interface, custom colors
Text editor integration
Fetch, edit page title; add tags and notes
Powerful search modes (regex, substring...)
Continuous search with on the fly mode switch
Open bookmarks and search results in browser
Manual encryption support
Auto-import from Firefox, Google Chrome and Chromium
Import/export bookmarks from/to HTML, Markdown or Orgfile
Shorten and expand URLs
Smart tag management using redirection (>>, >, <<)
Portable, merge-able database to sync between systems
Multithreaded full DB refresh
Shell completion scripts, man page with handy examples

Installation

Dependencies

Feature	Dependency
Scripting language	Python 3.4+
HTTP(S)	urllib3
Encryption	cryptography
Import browser exported html	beautifulsoup4

To install package dependencies using pip3, run:

# pip3 install urllib3 cryptography beautifulsoup4

or on Ubuntu:

# apt-get install python3-urllib3 python3-cryptography python3-bs4

To copy url to clipboard at the prompt, Buku uses xsel on Linux, pbcopy (default installed) on OS X and clip (default installed) on Windows.

From a package manager

AUR (pacman -S buku)
Debian (apt-get install buku)
Fedora (dnf install buku)
FreeBSD (pkg install www/py-buku)
Gentoo (emerge buku)
Homebrew (brew install buku)
NixOS (nix-env -i buku)
OpenBSD (pkg_add buku)
openSUSE (zypper in python3-buku)
PyPi (pip3 install buku)
Ubuntu (apt-get install buku)
Ubuntu PPA (apt-get install buku)
Void Linux (xbps-install -S buku)

Release packages

Packages for Arch Linux, CentOS, Debian, Fedora, openSUSE Leap and Ubuntu are available with the latest stable release.

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 or development version (risky).

Install 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/. Please refer to your shell's manual for installation instructions.

Usage

Cmdline options

usage: buku [OPTIONS] [KEYWORD [KEYWORD ...]]

Bookmark manager like a text-based mini-web.

POSITIONAL ARGUMENTS:
      KEYWORD              search keywords

GENERAL OPTIONS:
      -a, --add URL [tag, ...]
                           bookmark URL with comma-separated tags
      -u, --update [...]   update fields of an existing bookmark
                           accepts indices and ranges
                           refresh the title, if no edit options
                           if no arguments:
                           - update results when used with search
                           - otherwise refresh all titles
      -w, --write [editor|index]
                           open editor to edit a fresh bookmark
                           edit last bookmark, if index=-1
                           to specify index, EDITOR must be set
      -d, --delete [...]   remove bookmarks from DB
                           accepts indices or a single range
                           if no arguments:
                           - delete results when used with search
                           - otherwise delete all bookmarks
      -h, --help           show this information and exit
      -v, --version        show the program version and exit

EDIT OPTIONS:
      --url keyword        bookmark link
      --tag [+|-] [...]    comma-separated tags
                           clear bookmark tagset, if no arguments
                           '+' appends to, '-' removes from tagset
      --title [...]        bookmark title; if no arguments:
                           -a: do not set title, -u: clear title
      -c, --comment [...]  notes or description of the bookmark
                           clears description, if no arguments
      --immutable N        disable title fetch from web on update
                           N=0: mutable (default), N=1: immutable

SEARCH OPTIONS:
      -s, --sany [...]     find records with ANY matching keyword
                           this is the default search option
      -S, --sall [...]     find records matching ALL the keywords
                           special keywords -
                           "blank": entries with empty title/tag
                           "immutable": entries with locked title
      --deep               match substrings ('pen' matches 'opens')
      -r, --sreg expr      run a regex search
      -t, --stag [tag [,|+] ...] [- tag, ...]
                           search bookmarks by tags
                           use ',' to find entries matching ANY tag
                           use '+' to find entries matching ALL tags
                           excludes entries with tags after ' - '
                           list all tags, if no search keywords
      -x, --exclude [...]  omit records matching specified keywords

ENCRYPTION OPTIONS:
      -l, --lock [N]       encrypt DB in N (default 8) # iterations
      -k, --unlock [N]     decrypt DB in N (default 8) # iterations

POWER TOYS:
      --ai                 auto-import from Firefox/Chrome/Chromium
      -e, --export file    export bookmarks to Firefox format html
                           export markdown, if file ends with '.md'
                           format: [title](url), 1 entry per line
                           export orgfile, if file ends with '.org'
                           format: *[[url][title]], 1 entry per line
                           export buku DB, if file ends with '.db'
                           use --tag to export specific tags
      -i, --import file    import bookmarks html in Firefox format
                           import markdown, if file ends with '.md'
                           import orgfile, if file ends with '.org'
                           import buku DB, if file ends with '.db'
      -p, --print [...]    show record details by indices, ranges
                           print all bookmarks, if no arguments
                           -n shows the last n results (like tail)
      -f, --format N       limit fields in -p or Json search output
                           N=1: URL, N=2: URL and tag, N=3: title,
                           N=4: URL, title and tag. To omit DB index,
                           use N0, e.g., 10, 20, 30, 40.
      -j, --json           Json formatted output for -p and search
      --colors COLORS      set output colors in five-letter string
      --nc                 disable color output
      --np                 do not show the prompt, run and exit
      -o, --open [...]     browse bookmarks by indices and ranges
                           open a random bookmark, if no arguments
      --oa                 browse all search results immediately
      --replace old new    replace old tag with new tag everywhere
                           delete old tag, if new tag not specified
      --shorten index|URL  fetch shortened url from tny.im service
      --expand index|URL   expand a tny.im shortened url
      --suggest            show similar tags when adding bookmarks
      --tacit              reduce verbosity
      --threads N          max network connections in full refresh
                           default N=4, min N=1, max N=10
      -V                   check latest upstream version available
      -z, --debug          show debug information and verbose logs

SYMBOLS:
      >                    url
      +                    comment
      #                    tags

PROMPT KEYS:
    1-N                    browse search result indices and/or ranges
    a                      open all results in browser
    s keyword [...]        search for records with ANY keyword
    S keyword [...]        search for records with ALL keywords
    d                      match substrings ('pen' matches 'opened')
    r expression           run a regex search
    t [...]                search bookmarks by tags or show taglist
                           list index after a tag listing shows records with the tag
    o id|range [...]       browse bookmarks by indices and/or ranges
    p id|range [...]       print bookmarks by indices and/or ranges
    g [taglist id|range ...] [>>|>|<<] record id|range [...]
                           append, set, remove (all or specific) tags
    w [editor|id]          edit and add or update a bookmark
    c id                   copy url at search result index to clipboard
    O                      toggle try to open in a GUI browser
    ?                      show this help
    q, ^D, double Enter    exit buku

Colors

buku supports custom colors. Visit the wiki page on how to customize colors for more details.

Examples

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.

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

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.

Add a bookmark without a title (works for update too):

$ buku -a https://ddg.gg search engine, privacy --title

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.
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
```
Fetch and update only title for bookmark at 15012014:
```
$ buku -u 15012014
```
Update only comment for bookmark at 15012014:
```
$ buku -u 15012014 -c this is a new comment
```
Applies to --url, --title and --tag too.

Export bookmarks tagged tag 1 or tag 2 to HTML, markdown or orgfile:

$ buku -e bookmarks.html --tag tag 1, tag 2
$ buku -e bookmarks.md --tag tag 1, tag 2
$ buku -e bookmarks.org --tag tag 1, tag 2
$ buku -e bookmarks.db --tag tag 1, tag 2

All bookmarks are exported if --tag is not specified.

Import bookmarks from HTML, markdown or orgfile:

$ buku -i bookmarks.html
$ buku -i bookmarks.md
$ buku -i bookmarks.org
$ buku -i bookmarks.db

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.
Update or refresh full DB with page titles from the web:
```
$ buku -u
$ buku -u --tacit (show only failures and exceptions)
```
This operation does not modify the indexes, URLs, tags or comments. Only title is refreshed if fetched title is non-empty.
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.
Delete all bookmarks:
```
$ buku -d
```
Delete a range or list of bookmarks:
```
$ buku -d 100-200
$ buku -d 100 15 200
```
Search bookmarks for ANY of the keywords kernel and debugging in URL, title or tags:
```
$ buku kernel debugging
$ buku -s kernel debugging
```
Search bookmarks with ALL the keywords kernel and debugging in URL, title or tags:
```
$ buku -S kernel debugging
```
Search bookmarks tagged general kernel concepts:
```
$ buku --stag general kernel concepts
```
Search for bookmarks matching ANY of the tags kernel, debugging, general kernel concepts:
```
$ buku --stag kernel, debugging, general kernel concepts
```
Search for bookmarks matching ALL of the tags kernel, debugging, general kernel concepts:
```
$ buku --stag kernel + debugging + general kernel concepts
```
Search for bookmarks matching any of the keywords hello or world, excluding the keywords real and life, matching both the tags kernel and debugging, but excluding the tags general kernel concepts and books:
```
$ buku hello world --exclude real life --stag 'kernel + debugging - general kernel concepts, books'
```
List all unique tags alphabetically:
```
$ buku --stag
```

Run a search and update the results:

$ buku -s kernel debugging -u --tag + linux kernel

Run a search and delete the results:
```
$ buku -s kernel debugging -d
```
Encrypt or decrypt DB with custom number of iterations (15) to generate key:
```
$ buku -l 15
$ buku -k 15
```
The same number of iterations must be specified for one lock & unlock instance. Default is 8, if omitted.
Show details of bookmarks at index 15012014 and ranges 20-30, 40-50:
```
$ buku -p 20-30 15012014 40-50
```
Show details of the last 10 bookmarks:
```
$ buku -p -10
```
Show all bookmarks with real index from database:
```
$ buku -p
$ buku -p | more
```
Replace tag 'old tag' with 'new tag':
```
$ buku --replace 'old tag' 'new tag'
```
Delete tag 'old tag' from DB:
```
$ buku --replace 'old tag'
```
Append (or delete) tags 'tag 1', 'tag 2' to (or from) existing tags of bookmark at index 15012014:
```
$ buku -u 15012014 --tag + tag 1, tag 2
$ buku -u 15012014 --tag - tag 1, tag 2
```
Open URL at index 15012014 in browser:
```
$ buku -o 15012014
```
List bookmarks with no title or tags for bookkeeping:
```
$ buku -S blank
```
List bookmarks with immutable title:
```
$ buku -S immutable
```

Shorten URL www.google.com and the URL at index 20:

$ buku --shorten www.google.com
$ buku --shorten 20

Append, remove tags at prompt (taglist index to the left, bookmark index to the right):

// append tags at taglist indices 4 and 6-9 to existing tags in bookmarks at indices 5 and 2-3
buku (? for help) g 4 9-6 >> 5 3-2
// set tags at taglist indices 4 and 6-9 as tags in bookmarks at indices 5 and 2-3
buku (? for help) g 4 9-6 > 5 3-2
// remove all tags from bookmarks at indices 5 and 2-3
buku (? for help) g > 5 3-2
// remove tags at taglist indices 4 and 6-9 from tags in bookmarks at indices 5 and 2-3
buku (? for help) g 4 9-6 << 5 3-2

List bookmarks with colored output:
```
$ buku --colors oKlxm -p
```
More help:
```
$ buku -h
$ man buku
```

Troubleshooting

Editor integration

You may encounter issues with GUI editors which maintain only one instance by default and return immediately from other instances. Use the appropriate editor option to block the caller when a new document is opened. See issue #210 for gedit.

Collaborators

bukubrow, WebExtension for browser integration
oil, search-as-you-type cli frontend
buku_run, rofi frontend
pinku, A Pinboard-to-Buku importation utility