Provided by: buku_4.9+ds-1_all 
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, Chromium, Vivaldi, and MS Edge
* Open bookmarks and search results in browser
* Shorten, expand URLs
* 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 or Orgfile
* Smart tag management using redirection (>>, >, <<)
* Multithreaded full DB refresh
* Manual encryption support
* Shell completion scripts, man page with handy examples
OPERATIONAL NOTES
1. The database file is stored in:
- $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.
2. If the URL contains characters like ';', '&' or brackets they may be interpreted
specially by the shell. To avoid it, add the URL within single or double quotes ('/").
3. URLs are unique in DB. The same URL cannot be added twice.
4. Bookmarks with immutable titles are listed with '(L)' after the title.
5. Tags:
- 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.
6. Update operation:
- 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.
7. Delete operation:
- 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.
8. Search works in mysterious ways:
- 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.
9. Import:
- 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.
- JSON files exported from browser can be imported. Export to JSON is not supported.
10. Encryption is optional and manual. AES256 algorithm is used. To use encryption, the
database file should be unlocked (-k) before using buku and locked (-l) afterwards.
Between these 2 operations, the database file lies unencrypted on the disk, and NOT in
memory. Also, note that the database file is unencrypted on creation.
11. Editor support:
- 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.
12. Proxy support: please refer to the ENVIRONMENT section.
13. Alternative DB file:
- The option --db (to specify an alternative database file location) is app-only.
Manual usage is prone to issues arising from human error.
- Note that this option is useful if you want to store the db file in cloud synced
location. Another mechanism could be to have the db file synced and create a symlink
to it at the default location.
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. 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
--deep Search modifier to match substrings. Works with --sany, --sall.
-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
--ai Auto-import bookmarks from Firefox, Google Chrome, Chromium, Vivaldi, and Edge
browsers. (Firefox profile can be specified using environment variable
FIREFOX_PROFILE.)
-e --export file
Export bookmarks to Firefox bookmarks formatted HTML. Works with all search
options.
XBEL is used if file has extension '.xbel'.
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, XBEL if it is '.xbel', 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.
--nc Disable color output in all messages. Useful on terminals which can't handle ANSI
color codes or scripted environments.
-n --count N
Number of results to show per page (default 10).
--np Do not show the prompt, run and exit.
-o --open [...]
Open bookmarks by DB indices or ranges in browser. Open a random index if argument
is omitted.
--oa Open all search results immediately in the browser. Works best with --np. When used
along with --update or --delete, URLs are opened in the browser first and then
modified or deleted.
--replace old new
Replace old tag with new tag if both are passed; delete old tag if new tag is not
specified.
--url-redirect
when fetching an URL, use the resulting URL from following permanent redirects
(when combined with --export, the old URL is included as additional metadata).
--tag-redirect [tag]
when fetching an URL that causes permanent redirect, add a tag in specified pattern
(using 'http:{}' if not specified).
--tag-error [tag]
when fetching an URL that causes an HTTP error, add a tag in specified pattern
(using 'http:{}' if not specified).
--del-error [...]
when fetching an URL causes any (given) HTTP error, delete/do not add it. (Use a
parameter like '404' or '400-404,500')
--export-on [...]
export records affected by the above options, including removed info (requires
--update and --export; specific HTTP response filter can be provided).
--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.
--offline
Add a bookmark without connecting to the web.
--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.
--nostdin
Do not attempt to read data from standard input e.g. when the program is not
executed from a tty.
--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.
-V Check the latest upstream version available. This is FYI. It is possible the latest
upstream released version is still not available in your package manager as the
process takes a while.
-g --debug
Show debug information and additional logs.
PROMPT KEYS
1-N Browse search results by indices and ranges.
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.
a Open all search results in browser.
s keyword [...]
Search for records with ANY keyword.
S keyword [...]
Search for records with ALL keywords.
d Toggle deep search to match substrings ('pen' matches 'opened').
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.
c id Copy url at search result index to clipboard.
? Show help on prompt keys.
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
EDITOR If defined, will be used as the editor to edit bookmarks with option --write.
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
- index
- title
- URL
- description/comment/note
- tag
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:
┌───────┬───────────────────────────────────────────────────┐
│Letter │ Color/Style │
├───────├───────────────────────────────────────────────────┤
│a │ black │
│b │ red │
│c │ green │
│d │ yellow │
│e │ blue │
│f │ magenta │
│g │ cyan │
│h │ white │
│i │ bright black │
│j │ bright red │
│k │ bright green │
│l │ bright yellow │
│m │ bright blue │
│n │ bright magenta │
│o │ bright cyan │
│p │ bright white │
│A-H │ bold version of the lowercase-letter color │
│I-P │ bold version of the lowercase-letter bright color │
│x │ normal │
│X │ bold │
│y │ reverse video │
│Y │ bold reverse video │
└───────┴───────────────────────────────────────────────────┘
The default colors string is oKlxm, which stands for
- bright cyan index
- bold bright green title
- bright yellow URL
- normal description
- bright blue tag
Note that
- Bright colors (implemented as \x1b[90m - \x1b[97m) may not be available in all color-
capable terminal emulators;
- Some terminal emulators draw bold text in bright colors instead;
- Some terminal emulators only distinguish between bold and bright colors via a default-
off switch.
Please consult the manual of your terminal emulator as well as
https://en.wikipedia.org/wiki/ANSI_escape_code for details.
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 --no-stdin -a https://github.com/
In the output, >: url, +: comment, #: tags.
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
In the output, >: 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
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.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
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' in URL, title or
tags:
buku kernel debugging
buku -s kernel debugging
18. Search bookmarks with ALL the keywords 'kernel' and 'debugging' in URL, title or tags:
buku -S kernel debugging
19. Search bookmarks tagged 'general kernel concepts':
buku --stag general kernel concepts
20. Search for bookmarks matching ANY of the tags 'kernel', 'debugging', 'general kernel
concepts':
buku --stag kernel, debugging, general kernel concepts
21. Search for bookmarks matching ALL of the tags 'kernel', 'debugging', 'general kernel
concepts':
buku --stag kernel + debugging + general kernel concepts
22. 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'
23. List all unique tags alphabetically:
buku --stag
24. Run a search and update the results:
buku -s kernel debugging -u --tag + linux kernel
25. Run a search and delete the results:
buku -s kernel debugging -d
26. 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.
27. Show details of bookmarks at index 15012014 and ranges 20-30, 40-50:
buku -p 20-30 15012014 40-50
28. Show details of the last 10 bookmarks:
buku -p -10
29. Show all bookmarks with real index from database:
buku -p
buku -p | more
30. Replace tag 'old tag' with 'new tag':
buku --replace 'old tag' 'new tag'
31. Delete tag 'old tag' from DB:
buku --replace 'old tag'
32. 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
33. Open URL at index 15012014 in browser:
buku -o 15012014
34. List bookmarks with no title or tags for bookkeeping:
buku -S blank
35. List bookmarks with immutable title:
buku -S immutable
36. Shorten the URL www.google.com and the URL at index 20:
buku --shorten www.google.com
buku --shorten 20
37. 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
38. List bookmarks with colored output:
$ buku --colors oKlxm -p
39. Add a bookmark after following all permanent redirects, but only if the server doesn't
respond with an error (and there's no network failure)
buku --add http://wikipedia.net --url-redirect --del-error
2. Wikipedia
> https://www.wikipedia.org/
+ Wikipedia is a free online encyclopedia, created and edited by volunteers around the world and hosted by the Wikimedia Foundation.
40. Add a bookmark with tag 'http redirect' if the server responds with a permanent
redirect, or tag shaped like 'http 404' on an error response:
buku --add http://wikipedia.net/notfound --tag-redirect 'http redirect' --tag-error 'http {}'
[ERROR] [404] Not Found
3. Not Found
> http://wikipedia.net/notfound
# http 404,http redirect
41. Update all bookmarks matching the search by updating the URL if the server responds
with a permanent redirect, deleting the bookmark if the server responds with HTTP
error 400, 401, 402, 403, 404 or 500, or adding a tag shaped like 'http:{}' in case of
any other HTTP error; then export those affected by such changes into an HTML file,
marking deleted records as well as old URLs for those replaced by redirect.
buku -S ://wikipedia.net -u --url-redirect --tag-error --del-error 400-404,500 --export-on --export backup.html
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-2024 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.