BUKU

NAME

buku - Bookmark manager like a text-based mini-web

SYNOPSIS

buku [OPTIONS] [KEYWORD [KEYWORD ...]]

DESCRIPTION

buku is a command-line utility to store, tag, search and organize bookmarks.

Features

* Store bookmarks with auto-fetched title, tags and description
* Auto-import from Firefox, Google Chrome and Chromium
* Open bookmarks and search results in browser
* Shorten, expand URLs, browse cached page from 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, Markdown or Orgfile
* Smart tag management using redirection (>>, >, <<)
* Multithreaded full DB refresh, manual encryption support
* Shell completion scripts, man page with handy examples

OPERATIONAL NOTES

- $XDG_DATA_HOME/buku/bookmarks.db, if XDG_DATA_HOME is defined (first preference), or
- $HOME/.local/share/buku/bookmarks.db, if HOME is defined (second preference), or
- %APPDATA%\buku\bookmarks.db, if you are on Windows, or
- the current directory.

- Comma (’,’) is the tag delimiter in DB. A tag cannot have comma(s) in it. Tags are filtered (for unique tags) and sorted. Tags are stored in lower case and can be replaced, appended or deleted.
- Page keywords having a word to comma ratio > 3 are appended to description rather than tags.
- Parent folder (and subfolder) names are converted to all-lowercase tags during bookmarks HTML import.
- Releases prior to v2.7 support both capital and lower cases in tags. From v2.7 all tags are stored in lowercase. An undocumented option --fixtags is introduced to modify the older tags. It also fixes another issue where the same tag appears multiple times in the tagset of a record. Run buku --fixtags once.
- Tags can be edited from the prompt very easily using ’>>’ (append), ’>’ (overwrite) and ’<<’ (remove) symbols. The LHS of the operands denotes the indices and ranges of tags to apply (as listed by --tag or key ’t’ at prompt) and the RHS denotes the actual DB indices and ranges of the bookmarks to apply the change to.

- If --title, --tag or --comment is passed without argument, clear the corresponding field from DB.
- If --url is passed (and --title is omitted), update the title from web using the URL. Description is updated (if --comment is omitted). Tags remain untouched.
- If indices are passed without any other options (--url, --title, --tag, --comment and --immutable), read the URLs from DB and update titles, description and append tags from web. Bookmarks marked immutable are skipped.
- Can update bookmarks matching a search, when combined with any of the search options and no arguments to update are passed.

- When a record is deleted, the last record is moved to the index.
- Delete doesn’t work with range and indices provided together as arguments. It’s an intentional decision to avoid extra sorting, in-range checks and to keep the auto-DB compaction functionality intact. On the same lines, indices are deleted in descending order.
- Can delete bookmarks matching a search, when combined with any of the search options and no arguments to delete are passed.

- Case-insensitive.
- Matches words in URL, title and tags.
- --sany : match any of the keywords in URL, title or tags. Default search option.
- --sall : match all the keywords in URL, title or tags.
- --deep : match substrings (’match’ matches ’rematched’) in URL, title and tags.
- --sreg : match a regular expression (ignores --deep).
- --stag : search bookmarks by tags, or list all tags alphabetically with usage count (if no arguments). Delimit the list of tags in the query with ’,’ to search for bookmarks that match ANY of the listed tags. Delimit tags with ’+’ to search for bookmarks that match ALL of the listed tags. Note that ’,’ and ’+’ cannot be used together in the same search. Exclude bookmarks matching certain tags from the results by using ’ - ’ followed by the tags. Note that the ’ - ’ operator and the ’ + ’ delimiter must be space separated: ’ - ’ instead of ’-’ and ’ + ’ instead of ’+’. This is to distinguish them from hyphenated tags (e.g., ’some-tag-name’) and tags with ’+’s (e.g., ’some+tag+name’).
- Search for keywords along with tag filtering is possible. Two searches are issued (one for keywords and another for tags) and the intersection of the 2 sets is returned as the resultset.
- Search results are indexed incrementally. This index is different from actual database index of a bookmark record which is shown within ’[]’ after the title.
- Results for any keyword matches are ordered by the number of keyword matches - results matching more keywords (match score) will appear earlier in the list. Results having the same number of matches will be ranked by their record DB index. If only one keyword is searched, results will be ordered by DB index, since all matching records will have the same match score.

- Auto-import looks in the default installation path and default user profile.
- URLs starting with ’place:’, ’file://’ and ’apt:’ are ignored during import.
- Parent folder (and subfolder) names are automatically imported as tags if --tacit is used.
- Tags are merged even if bookmark URL exists when --tacit is used.

- A single bookmark can be edited before adding. The editor can be set using the environment variable *EDITOR* or by explicitly specifying the editor. The latter takes precedence. If -a is used along with -w, the details are populated in the editor template.
- In case of edit and update (a single bookmark), the existing record details are fetched from DB and populated in the editor template. The environment variable EDITOR must be set. Note that -u works independently of -w.
- All lines beginning with "#" will be stripped. Then line 1 will be treated as the URL, line 2 will be the title, line 3 will be comma separated tags, and the rest of the lines will be parsed as descriptions.

- The option --db (to specify an alternative database file location) is app-only. Manual usage is prone to issues arising from human error.

GENERAL OPTIONS

-a --add URL [tag, ...]

Bookmark URL along with comma-separated tags. A tag can have multiple words.

-u --update [...]

Update fields of the bookmarks at specified indices in DB. If no arguments are specified, all titles and descriptions are refreshed from the web. Tags remain untouched. Works with update modifiers for the fields url, title, tag and comment. If only indices are passed without any edit options, titles and descriptions are fetched and updated (if not empty). Accepts hyphenated ranges and space-separated indices. Updates search results when used with search options, if no arguments.

-w --write [editor|index]

Edit a bookmark in editor before adding it. To edit and update an existing bookmark, the index should be passed. However, in this case the environment variable EDITOR must be set. The last record is opened in EDITOR if index=-1.

-d --delete [...]

Delete bookmarks. Accepts space-separated list of indices (e.g. 5 6 23 4 110 45) or a single hyphenated range (e.g. 100-200). Note that range and list don’t work together. Deletes search results when combined with search options, if no arguments.

-v --version

Show program version and exit.

-h --help

Show program help and exit.

EDIT OPTIONS

--url [...]

Specify the URL, works with --update only. Fetches and updates title if --title is not used.

--tag [+|-] [...]

Specify comma separated tags, works with --add, --update. Clears the tags, if no arguments passed. Appends or deletes tags, if list of tags is preceded by ’+’ or ’-’ respectively.

--title [...]

Manually specify the title, works with --add, --update. Omits or clears the title, if no arguments passed.

-c --comment [...]

Add notes or description of the bookmark, works with --add, --update. Clears the comment, if no arguments passed.

--immutable N

Set the title, description and tags of a bookmark immutable during autorefresh. Works with --add, --update. N=1 sets the immutable flag, N=0 removes it. If omitted, bookmarks are added with N=0.

SEARCH OPTIONS

-s --sany keyword [...]

Search bookmarks with ANY of the keyword(s) in URL, title or tags and show the results. Prompts to enter result number to open in browser. Note that the sequential result index is not the DB index. The DB index is shown within ’[]’ after the title.
This is the default search option for positional arguments if no other search option is specified.

-S --sall keyword [...]

Search bookmarks with ALL keywords in URL, title or tags and show the results. Behaviour same as --sany.
Special keywords:
"blank": list entries with empty title/tag
"immutable": list entries with locked title
NOTE: To search the keywords, use --sany

-r --sreg expression

Scan for a regular expression match.

-t --stag [tag [,|+] ...] [- tag, ...]

Search bookmarks by tags.
Use ’,’ delimiter to find entries matching ANY of the tags
Use ’ + ’ delimiter to find entries matching ALL of the tags. (Note that the ’ + ’ delimiter must be space separated)
NOTE: Cannot combine ’,’ and ’+’ in the same search
Use ’ - ’ to exclude bookmarks that match the tags that follow. (Note that the ’-’ operator must be space separated).
List all tags alphabetically, if no arguments. The usage count (number of bookmarks having the tag) is shown within first brackets.

-x --exclude keyword [...]

Exclude bookmarks matching the specified keywords. Works with --sany, --sall, --sreg and --stag.

ENCRYPTION OPTIONS

-l --lock [N]

Encrypt (lock) the DB file with N (> 0, default 8) hash passes to generate key.

-k --unlock [N]

Decrypt (unlock) the DB file with N (> 0, default 8) hash passes to generate key.

POWER OPTIONS

-e --export file

Export bookmarks to Firefox bookmarks formatted HTML. Works with all search options.
Markdown is used if file has extension ’.md’. Markdown format: [title](url), 1 entry per line.
Orgfile is used if file has extension ’.org’ Orgfile format: * [[url][title]], 1 entry per line.
A buku database is generated if file has extension ’.db’.

-i --import file

Import bookmarks from Firefox bookmarks formatted HTML. file is considered Firefox-exported JSON if it has ’.json’ extension, Markdown (compliant with --export format) if it is ’.md’, Orgfile if the extension is ’.org’ or another buku database if the extension is ’.db’.

-p --print [...]

Show details (DB index, URL, title, tags and comment) of bookmark record by DB index. If no arguments, all records with actual index from DB are shown. Accepts hyphenated ranges and space-separated indices. A negative value (introduced for convenience) behaves like the tail utility, e.g., -n shows the details of the last n bookmarks.

-f --format N

Show selective monochrome output with specific fields. Works with --print. Search results honour the option when used along with --json. Useful for creating batch scripts.
N = 1, show only URL.
N = 2, show URL and tags in a single line.
N = 3, show only title.
N = 4, show URL, title and tags in a single line.
N = 5, show title and tags in a single line.
To omit DB index from printed results, use N0, e.g., 10, 20, 30, 40, 50.

-j --json

Output data formatted as JSON, works with --print output and search results.

--colors COLORS

Set output colors. Refer to the COLORS section below for details.

-n --count N

Number of results to show per page (default 10).

-o --open [...]

Open bookmarks by DB indices or ranges in browser. Open a random index if argument is omitted.

--replace old new

Replace old tag with new tag if both are passed; delete old tag if new tag is not specified.

--shorten index|URL

Shorten the URL at DB index or an independent URL using the tny.im URL shortener service.

--expand index|URL

Expand the URL at DB index or an independent URL shortened using tny.im.

--cached index|URL

Browse the latest cached version of the URL at DB index or an independent URL using the Wayback Machine. Useful for viewing the content of bookmarks which are not live any more.

--suggest

Show a list of similar tags to choose from when adding a new bookmark.

--tacit

Show lesser output. Reduces the verbosity of certain operations like add, update etc.

--threads

Maximum number of parallel network connection threads to use during full DB refresh. By default 4 connections are spawned. N can range from 1 to 10.

-g --debug

Show debug information and additional logs.

PROMPT KEYS

O [id|range [...]]

Try to open search results or indices (when not in a search context) in a GUI browser. Toggle try to open urls in a GUI based browser (even if BROWSER is set) if no arguments. Toggling is useful when trying to open bookmarks by DB index.

s keyword [...]

Search for records with ANY keyword.

S keyword [...]

Search for records with ALL keywords.

r expression

Run a regular expression search.

t [...]

Search bookmarks by a tag. List all tags alphabetically, if no arguments.

g taglist id|range [...] [>>|>|<<] [record id|range ...]

Append, set, remove specific or all tags by indices and/or ranges to bookmark indices and/or ranges (see EXAMPLES section below). Search by space-separated taglist id(s) and/or range if records are omitted.

o id|range [...]

Browse bookmarks by indices and/or ranges.

p id|range [...]

Print bookmarks by indices and/or ranges.

w [editor|id]

Edit and add or update a bookmark.

q, ^D, double Enter

Exit buku.

ENVIRONMENT

Completion scripts

Shell completion scripts for Bash, Fish and Zsh can be found in:
https://github.com/jarun/buku/blob/master/auto-completion

BROWSER

Overrides the default browser. Refer to:
http://docs.python.org/library/webbrowser.html

https_proxy

If defined, will be used to access http and https resources through the configured proxy. Supported format:
http[s]://[username:password@]proxyhost:proxyport/

GUI integration

buku can be integrated in a GUI environment with simple tweaks. Please refer to:
https://github.com/jarun/buku/wiki/System-integration

COLORS

buku allows you to customize the color scheme via a five-letter string, reminiscent of BSD LSCOLORS. The five letters represent the colors of

respectively. The five-letter string is passed is as the argument to
the --colors option, or as the value of the environment variable
BUKU_COLORS.
We offer the following colors/styles:

The default colors string is oKlxm, which stands for

Note that

Please consult the manual of your terminal emulator as well as
https://en.wikipedia.org/wiki/ANSI_escape_code for details.

EXAMPLES

buku -w
buku -w ’gedit -w’
buku -w ’macvim -f’ -a https://ddg.gg search engine, privacy

buku -a https://ddg.gg search engine, privacy -c Search engine with perks

buku -a https://ddg.gg search engine, privacy --title ’DDG’ --immutable 1

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

buku -w 15012014

buku -u 15012014 --url http://ddg.gg/ --tag web search, utilities -c Private search engine

buku -u 15012014

buku -u 15012014 -c this is a new comment

buku -e bookmarks.html --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

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

buku -u 15012014 -c

buku -u
buku -u --tacit (show only failures and exceptions)

buku -d 15012014

buku -d

buku -d 100-200
buku -d 100 15 200

buku kernel debugging
buku -s kernel debugging

buku -S kernel debugging

buku --stag general kernel concepts

buku --stag kernel, debugging, general kernel concepts

buku --stag kernel + debugging + general kernel concepts

buku hello world --exclude real life --stag ’kernel + debugging - general kernel concepts, books’

buku --stag

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

buku -s kernel debugging -d

buku -l 15
buku -k 15

buku -p 20-30 15012014 40-50

buku -p -10

buku -p
buku -p | more

buku --replace ’old tag’ ’new tag’

buku --replace ’old tag’

buku -u 15012014 --tag + tag 1, tag 2
buku -u 15012014 --tag - tag 1, tag 2

buku -o 15012014

buku -S blank

buku -S immutable

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

// 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

$ buku --colors oKlxm -p

AUTHOR

Arun Prakash Jana <engineerarun@gmail.com>

HOME

https://github.com/jarun/buku

WIKI

https://github.com/jarun/buku/wiki

REPORTING BUGS

https://github.com/jarun/buku/issues

LICENSE

Copyright © 2015-2021 Arun Prakash Jana <engineerarun@gmail.com>.

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.