1BUKU(1) User Commands BUKU(1)
2
6 buku - Bookmark manager like a text-based mini-web
7
9 buku [OPTIONS] [KEYWORD [KEYWORD ...]]
10
12 buku is a command-line utility to store, tag, search and organize book‐
13 marks.
14 Features
16 * Store bookmarks with auto-fetched title, tags and description
18 * Auto-import from Firefox, Google Chrome and Chromium
19 * Open bookmarks and search results in browser
20 * Shorten, expand URLs, browse cached page from Wayback Machine
21 * Text editor integration
22 * Lightweight, clean interface, custom colors
23 * Powerful search options (regex, substring...)
24 * Continuous search with on the fly mode switch
25 * Portable, merge-able database to sync between systems
26 * Import/export bookmarks from/to HTML, Markdown or Orgfile
27 * Smart tag management using redirection (>>, >, <<)
28 * Multithreaded full DB refresh, manual encryption support
29 * Shell completion scripts, man page with handy examples
30
32 1. The database file is stored in:
33 - $XDG_DATA_HOME/buku/bookmarks.db, if XDG_DATA_HOME is defined
34 (first preference), or
35 - $HOME/.local/share/buku/bookmarks.db, if HOME is defined (sec‐
36 ond preference), or
37 - %APPDATA%\buku\bookmarks.db, if you are on Windows, or
38 - the current directory.
39 2. If the URL contains characters like ';', '&' or brackets they may
41 be interpreted specially by the shell. To avoid it, add the URL
42 within single or double quotes ('/").
43 3. URLs are unique in DB. The same URL cannot be added twice.
45 4. Bookmarks with immutable titles are listed with '(L)' after the
47 title.
48 5. Tags:
50 - Comma (',') is the tag delimiter in DB. A tag cannot have
51 comma(s) in it. Tags are filtered (for unique tags) and sorted.
52 Tags are stored in lower case and can be replaced, appended or
53 deleted.
54 - Page keywords having a word to comma ratio > 3 are appended to
55 description rather than tags.
56 - Parent folder (and subfolder) names are converted to all-lower‐
57 case tags during bookmarks HTML import.
58 - Releases prior to v2.7 support both capital and lower cases in
59 tags. From v2.7 all tags are stored in lowercase. An undocumented
60 option --fixtags is introduced to modify the older tags. It also
61 fixes another issue where the same tag appears multiple times in
62 the tagset of a record. Run buku --fixtags once.
63 - Tags can be edited from the prompt very easily using '>>'
64 (append), '>' (overwrite) and '<<' (remove) symbols. The LHS of the
65 operands denotes the indices and ranges of tags to apply (as listed
66 by --tag or key 't' at prompt) and the RHS denotes the actual DB
67 indices and ranges of the bookmarks to apply the change to.
68 6. Update operation:
70 - If --title, --tag or --comment is passed without argument,
71 clear the corresponding field from DB.
72 - If --url is passed (and --title is omitted), update the title
73 from web using the URL. Description is updated (if --comment is
74 omitted). Tags remain untouched.
75 - If indices are passed without any other options (--url,
76 --title, --tag, --comment and --immutable), read the URLs from DB
77 and update titles, description and append tags from web. Bookmarks
78 marked immutable are skipped.
79 - Can update bookmarks matching a search, when combined with any
80 of the search options and no arguments to update are passed.
81 7. Delete operation:
83 - When a record is deleted, the last record is moved to the
84 index.
85 - Delete doesn't work with range and indices provided together as
86 arguments. It's an intentional decision to avoid extra sorting, in-
87 range checks and to keep the auto-DB compaction functionality
88 intact. On the same lines, indices are deleted in descending order.
89 - Can delete bookmarks matching a search, when combined with any
90 of the search options and no arguments to delete are passed.
91 8. Search works in mysterious ways:
93 - Case-insensitive.
94 - Matches words in URL, title and tags.
95 - --sany : match any of the keywords in URL, title or tags.
96 Default search option.
97 - --sall : match all the keywords in URL, title or tags.
98 - --deep : match substrings (`match` matches `rematched`) in URL,
99 title and tags.
100 - --sreg : match a regular expression (ignores --deep).
101 - --stag : search bookmarks by tags, or list all tags alphabeti‐
102 cally with usage count (if no arguments). Delimit the list of tags
103 in the query with `,` to search for bookmarks that match ANY of the
104 listed tags. Delimit tags with `+` to search for bookmarks that
105 match ALL of the listed tags. Note that `,` and `+` cannot be used
106 together in the same search. Exclude bookmarks matching certain
107 tags from the results by using ` - ` followed by the tags. Note
108 that the ` - ` operator and the ` + ` delimiter must be space sepa‐
109 rated: ` - ` instead of `-` and ` + ` instead of `+`. This is to
110 distinguish them from hyphenated tags (e.g., `some-tag-name`) and
111 tags with '+'s (e.g., `some+tag+name`).
112 - Search for keywords along with tag filtering is possible. Two
113 searches are issued (one for keywords and another for tags) and the
114 intersection of the 2 sets is returned as the resultset.
115 - Search results are indexed incrementally. This index is differ‐
116 ent from actual database index of a bookmark record which is shown
117 within '[]' after the title.
118 - Results for any keyword matches are ordered by the number of
119 keyword matches - results matching more keywords (match score) will
120 appear earlier in the list. Results having the same number of
121 matches will be ranked by their record DB index. If only one key‐
122 word is searched, results will be ordered by DB index, since all
123 matching records will have the same match score.
124 9. Import:
126 - Auto-import looks in the default installation path and default
127 user profile.
128 - URLs starting with `place:`, `file://` and `apt:` are ignored
129 during import.
130 - Parent folder (and subfolder) names are automatically imported
131 as tags if --tacit is used.
132 - Tags are merged even if bookmark URL exists when --tacit is
133 used.
134 10. Encryption is optional and manual. AES256 algorithm is used. To use
136 encryption, the database file should be unlocked (-k) before using
137 buku and locked (-l) afterwards. Between these 2 operations, the
138 database file lies unencrypted on the disk, and NOT in memory.
139 Also, note that the database file is unencrypted on creation.
140 11. Editor support:
142 - A single bookmark can be edited before adding. The editor can
143 be set using the environment variable *EDITOR* or by explicitly
144 specifying the editor. The latter takes precedence. If -a is used
145 along with -w, the details are populated in the editor template.
146 - In case of edit and update (a single bookmark), the existing
147 record details are fetched from DB and populated in the editor tem‐
148 plate. The environment variable EDITOR must be set. Note that -u
149 works independently of -w.
150 - All lines beginning with "#" will be stripped. Then line 1 will
151 be treated as the URL, line 2 will be the title, line 3 will be
152 comma separated tags, and the rest of the lines will be parsed as
153 descriptions.
154 12. Proxy support: please refer to the ENVIRONMENT section.
156 13. Alternative DB file:
158 - The option --db (to specify an alternative database file loca‐
159 tion) is app-only. Manual usage is prone to issues arising from
160 human error.
161
163 -a --add URL [tag, ...]
164 Bookmark URL along with comma-separated tags. A tag can have
165 multiple words.
166 -u --update [...]
168 Update fields of the bookmarks at specified indices in DB. If no
169 arguments are specified, all titles and descriptions are
170 refreshed from the web. Tags remain untouched. Works with update
171 modifiers for the fields url, title, tag and comment. If only
172 indices are passed without any edit options, titles and descrip‐
173 tions are fetched and updated (if not empty). Accepts hyphenated
174 ranges and space-separated indices. Updates search results when
175 used with search options, if no arguments.
176 -w --write [editor|index]
178 Edit a bookmark in editor before adding it. To edit and update
179 an existing bookmark, the index should be passed. However, in
180 this case the environment variable EDITOR must be set. The last
181 record is opened in EDITOR if index=-1.
182 -d --delete [...]
184 Delete bookmarks. Accepts space-separated list of indices (e.g.
185 5 6 23 4 110 45) or a single hyphenated range (e.g. 100-200).
186 Note that range and list don't work together. Deletes search
187 results when combined with search options, if no arguments.
188 -v --version
190 Show program version and exit.
191 -h --help
193 Show program help and exit.
194
196 --url [...]
197 Specify the URL, works with --update only. Fetches and updates
198 title if --title is not used.
199 --tag [+|-] [...]
201 Specify comma separated tags, works with --add, --update. Clears
202 the tags, if no arguments passed. Appends or deletes tags, if
203 list of tags is preceded by '+' or '-' respectively.
204 --title [...]
206 Manually specify the title, works with --add, --update. Omits or
207 clears the title, if no arguments passed.
208 -c --comment [...]
210 Add notes or description of the bookmark, works with --add,
211 --update. Clears the comment, if no arguments passed.
212 --immutable N
214 Set the title, description and tags of a bookmark immutable dur‐
215 ing autorefresh. Works with --add, --update. N=1 sets the
216 immutable flag, N=0 removes it. If omitted, bookmarks are added
217 with N=0.
218
220 -s --sany keyword [...]
221 Search bookmarks with ANY of the keyword(s) in URL, title or
222 tags and show the results. Prompts to enter result number to
223 open in browser. Note that the sequential result index is not
224 the DB index. The DB index is shown within '[]' after the title.
225 This is the default search option for positional arguments if no
226 other search option is specified.
227 -S --sall keyword [...]
229 Search bookmarks with ALL keywords in URL, title or tags and
230 show the results. Behaviour same as --sany.
231 Special keywords:
232 "blank": list entries with empty title/tag
233 "immutable": list entries with locked title
234 NOTE: To search the keywords, use --sany
235 --deep Search modifier to match substrings. Works with --sany, --sall.
237 -r --sreg expression
239 Scan for a regular expression match.
240 -t --stag [tag [,|+] ...] [- tag, ...]
242 Search bookmarks by tags.
243 Use ',' delimiter to find entries matching ANY of the tags
244 Use ' + ' delimiter to find entries matching ALL of the tags.
245 (Note that the ' + ' delimiter must be space separated)
246 NOTE: Cannot combine ',' and '+' in the same search
247 Use ' - ' to exclude bookmarks that match the tags that follow.
248 (Note that the '-' operator must be space separated).
249 List all tags alphabetically, if no arguments. The usage count
250 (number of bookmarks having the tag) is shown within first
251 brackets.
252 -x --exclude keyword [...]
254 Exclude bookmarks matching the specified keywords. Works with
255 --sany, --sall, --sreg and --stag.
256
258 -l --lock [N]
259 Encrypt (lock) the DB file with N (> 0, default 8) hash passes
260 to generate key.
261 -k --unlock [N]
263 Decrypt (unlock) the DB file with N (> 0, default 8) hash passes
264 to generate key.
265
267 --ai Auto-import bookmarks from Firefox, Google Chrome and Chromium
268 browsers.
269 -e --export file
271 Export bookmarks to Firefox bookmarks formatted HTML. Works with
272 all search options.
273 Markdown is used if file has extension '.md'. Markdown format:
274 [title](url), 1 entry per line.
275 Orgfile is used if file has extension '.org' Orgfile format: *
276 [[url][title]], 1 entry per line.
277 A buku database is generated if file has extension '.db'.
278 -i --import file
280 Import bookmarks from Firefox bookmarks formatted HTML. file is
281 considered Firefox-exported JSON if it has '.json' extension,
282 Markdown (compliant with --export format) if it is '.md',
283 Orgfile if the extension is '.org' or another buku database if
284 the extension is '.db'.
285 -p --print [...]
287 Show details (DB index, URL, title, tags and comment) of book‐
288 mark record by DB index. If no arguments, all records with
289 actual index from DB are shown. Accepts hyphenated ranges and
290 space-separated indices. A negative value (introduced for conve‐
291 nience) behaves like the tail utility, e.g., -n shows the
292 details of the last n bookmarks.
293 -f --format N
295 Show selective monochrome output with specific fields. Works
296 with --print. Search results honour the option when used along
297 with --json. Useful for creating batch scripts.
298 N = 1, show only URL.
299 N = 2, show URL and tags in a single line.
300 N = 3, show only title.
301 N = 4, show URL, title and tags in a single line.
302 N = 5, show title and tags in a single line.
303 To omit DB index from printed results, use N0, e.g., 10, 20, 30,
304 40, 50.
305 -j --json
307 Output data formatted as JSON, works with --print output and
308 search results.
309 --colors COLORS
311 Set output colors. Refer to the COLORS section below for
312 details.
313 --nc Disable color output in all messages. Useful on terminals which
315 can't handle ANSI color codes or scripted environments.
316 -n --count N
318 Number of results to show per page (default 10).
319 --np Do not show the prompt, run and exit.
321 -o --open [...]
323 Open bookmarks by DB indices or ranges in browser. Open a random
324 index if argument is omitted.
325 --oa Open all search results immediately in the browser. Works best
327 with --np. When used along with --update or --delete, URLs are
328 opened in the browser first and then modified or deleted.
329 --replace old new
331 Replace old tag with new tag if both are passed; delete old tag
332 if new tag is not specified.
333 --shorten index|URL
335 Shorten the URL at DB index or an independent URL using the
336 tny.im URL shortener service.
337 --expand index|URL
339 Expand the URL at DB index or an independent URL shortened using
340 tny.im.
341 --cached index|URL
343 Browse the latest cached version of the URL at DB index or an
344 independent URL using the Wayback Machine. Useful for viewing
345 the content of bookmarks which are not live any more.
346 --suggest
348 Show a list of similar tags to choose from when adding a new
349 bookmark.
350 --tacit
352 Show lesser output. Reduces the verbosity of certain operations
353 like add, update etc.
354 --threads
356 Maximum number of parallel network connection threads to use
357 during full DB refresh. By default 4 connections are spawned. N
358 can range from 1 to 10.
359 -V Check the latest upstream version available. This is FYI. It is
361 possible the latest upstream released version is still not
362 available in your package manager as the process takes a while.
363 -g --debug
365 Show debug information and additional logs.
366
368 1-N Browse search results by indices and ranges.
369 O [id|range [...]]
371 Try to open search results or indices (when not in a search con‐
372 text) in a GUI browser. Toggle try to open urls in a GUI based
373 browser (even if BROWSER is set) if no arguments. Toggling is
374 useful when trying to open bookmarks by DB index.
375 a Open all search results in browser.
377 s keyword [...]
379 Search for records with ANY keyword.
380 S keyword [...]
382 Search for records with ALL keywords.
383 d Toggle deep search to match substrings ('pen' matches 'opened').
385 r expression
387 Run a regular expression search.
388 t [...]
390 Search bookmarks by a tag. List all tags alphabetically, if no
391 arguments.
392 g taglist id|range [...] [>>|>|<<] [record id|range ...]
394 Append, set, remove specific or all tags by indices and/or
395 ranges to bookmark indices and/or ranges (see EXAMPLES section
396 below). Search by space-separated taglist id(s) and/or range if
397 records are omitted.
398 o id|range [...]
400 Browse bookmarks by indices and/or ranges.
401 p id|range [...]
403 Print bookmarks by indices and/or ranges.
404 w [editor|id]
406 Edit and add or update a bookmark.
407 c id Copy url at search result index to clipboard.
409 ? Show help on prompt keys.
411 q, ^D, double Enter
413 Exit buku.
414
416 Completion scripts
417 Shell completion scripts for Bash, Fish and Zsh can be found in:
418 https://github.com/jarun/buku/blob/master/auto-completion
419 BROWSER
421 Overrides the default browser. Refer to:
422 http://docs.python.org/library/webbrowser.html
423 EDITOR If defined, will be used as the editor to edit bookmarks with
425 option --write.
426 https_proxy
428 If defined, will be used to access http and https resources
429 through the configured proxy. Supported format:
430 http[s]://[username:password@]proxyhost:proxyport/
431 GUI integration
433 buku can be integrated in a GUI environment with simple tweaks.
434 Please refer to:
435 https://github.com/jarun/buku/wiki/System-integration
436
438 buku allows you to customize the color scheme via a five-letter string,
439 reminiscent of BSD LSCOLORS. The five letters represent the colors of
440 - index
442 - title
443 - URL
444 - description/comment/note
445 - tag
446 respectively. The five-letter string is passed is as the argument to
448 the --colors option, or as the value of the environment variable
449 BUKU_COLORS.
450 We offer the following colors/styles:
452 ┌───────┬───────────────────────────────────────────────────┐
454 │Letter │ Color/Style │
455 ├───────├───────────────────────────────────────────────────┤
456 │a │ black │
457 │b │ red │
458 │c │ green │
459 │d │ yellow │
460 │e │ blue │
461 │f │ magenta │
462 │g │ cyan │
463 │h │ white │
464 │i │ bright black │
465 │j │ bright red │
466 │k │ bright green │
467 │l │ bright yellow │
468 │m │ bright blue │
469 │n │ bright magenta │
470 │o │ bright cyan │
471 │p │ bright white │
472 │A-H │ bold version of the lowercase-letter color │
473 │I-P │ bold version of the lowercase-letter bright color │
474 │x │ normal │
475 │X │ bold │
476 │y │ reverse video │
477 │Y │ bold reverse video │
478 └───────┴───────────────────────────────────────────────────┘
479 The default colors string is oKlxm, which stands for
481 - bright cyan index
483 - bold bright green title
484 - bright yellow URL
485 - normal description
486 - bright blue tag
487 Note that
489 - Bright colors (implemented as \x1b[90m - \x1b[97m) may not be avail‐
491 able in all color-capable terminal emulators;
492 - Some terminal emulators draw bold text in bright colors instead;
494 - Some terminal emulators only distinguish between bold and bright col‐
496 ors via a default-off switch.
497 Please consult the manual of your terminal emulator as well as
499 https://en.wikipedia.org/wiki/ANSI_escape_code for details.
500
503 1. Edit and add a bookmark from editor:
504 buku -w
506 buku -w 'gedit -w'
507 buku -w 'macvim -f' -a https://ddg.gg search engine, privacy
508 The first command picks editor from the environment variable EDI‐
510 TOR. The second command opens gedit in blocking mode. The third
511 command opens macvim with option -f and the URL and tags populated
512 in template.
513 2. Add a bookmark with tags 'search engine' and 'privacy', comment
515 'Search engine with perks', fetch page title from the web:
516 buku -a https://ddg.gg search engine, privacy -c Search engine with perks
518 In the output, >: url, +: comment, #: tags.
520 3. Add a bookmark with tags 'search engine' & 'privacy' and immutable
522 custom title 'DDG':
523 buku -a https://ddg.gg search engine, privacy --title 'DDG' --immutable 1
525 Note that URL must precede tags.
527 4. Add a bookmark without a title (works for update too):
529 buku -a https://ddg.gg search engine, privacy --title
531 5. Edit and update a bookmark from editor:
533 buku -w 15012014
535 This will open the existing bookmark's details in the editor for
537 modifications. Environment variable EDITOR must be set.
538 6. Update existing bookmark at index 15012014 with new URL, tags and
540 comments, fetch title from the web:
541 buku -u 15012014 --url http://ddg.gg/ --tag web search, utilities -c Private search engine
543 7. Fetch and update only title for bookmark at 15012014:
545 buku -u 15012014
547 8. Update only comment for bookmark at 15012014:
549 buku -u 15012014 -c this is a new comment
551 Applies to --url, --title and --tag too.
553 9. Export bookmarks tagged 'tag 1' or 'tag 2' to HTML, Markdown,
555 Orgfile or a new database:
556 buku -e bookmarks.html --stag tag 1, tag 2
558 buku -e bookmarks.md --stag tag 1, tag 2
559 buku -e bookmarks.org --stag tag 1, tag 2
560 buku -e bookmarks.db --stag tag 1, tag 2
561 All bookmarks are exported if search is not opted.
563 10. Import bookmarks from HTML, Markdown or Orgfile:
565 buku -i bookmarks.html
567 buku -i bookmarks.md
568 buku -i bookmarks.db
569 11. Delete only comment for bookmark at 15012014:
571 buku -u 15012014 -c
573 Applies to --title and --tag too. URL cannot be deleted without
575 deleting the bookmark.
576 12. Update or refresh full DB with page titles from the web:
578 buku -u
580 buku -u --tacit (show only failures and exceptions)
581 This operation can update the title or description fields of non-
583 immutable bookmarks by parsing the fetched page. Fields are updated
584 only if the fetched fields are non-empty. Tags remain untouched.
585 13. Delete bookmark at index 15012014:
587 buku -d 15012014
589 The last index is moved to the deleted index to keep the DB com‐
591 pact. Add --tacit to delete without confirmation.
592 14. Delete all bookmarks:
594 buku -d
596 15. Delete a range or list of bookmarks:
598 buku -d 100-200
600 buku -d 100 15 200
601 16. Search bookmarks for ANY of the keywords 'kernel' and 'debugging'
603 in URL, title or tags:
604 buku kernel debugging
606 buku -s kernel debugging
607 17. Search bookmarks with ALL the keywords 'kernel' and 'debugging' in
609 URL, title or tags:
610 buku -S kernel debugging
612 18. Search bookmarks tagged 'general kernel concepts':
614 buku --stag general kernel concepts
616 19. Search for bookmarks matching ANY of the tags 'kernel', 'debug‐
618 ging', 'general kernel concepts':
619 buku --stag kernel, debugging, general kernel concepts
621 20. Search for bookmarks matching ALL of the tags 'kernel', 'debug‐
623 ging', 'general kernel concepts':
624 buku --stag kernel + debugging + general kernel concepts
626 21. Search for bookmarks matching any of the keywords 'hello' or
628 'world', excluding the keywords 'real' and 'life', matching both
629 the tags 'kernel' and 'debugging', but excluding the tags 'general
630 kernel concepts' and 'books':
631 buku hello world --exclude real life --stag 'kernel + debugging - general kernel concepts, books'
633 22. List all unique tags alphabetically:
635 buku --stag
637 23. Run a search and update the results:
639 buku -s kernel debugging -u --tag + linux kernel
641 24. Run a search and delete the results:
643 buku -s kernel debugging -d
645 25. Encrypt or decrypt DB with custom number of iterations (15) to gen‐
647 erate key:
648 buku -l 15
650 buku -k 15
651 The same number of iterations must be specified for one lock &
653 unlock instance. Default is 8, if omitted.
654 26. Show details of bookmarks at index 15012014 and ranges 20-30,
656 40-50:
657 buku -p 20-30 15012014 40-50
659 27. Show details of the last 10 bookmarks:
661 buku -p -10
663 28. Show all bookmarks with real index from database:
665 buku -p
667 buku -p | more
668 29. Replace tag 'old tag' with 'new tag':
670 buku --replace 'old tag' 'new tag'
672 30. Delete tag 'old tag' from DB:
674 buku --replace 'old tag'
676 31. Append (or delete) tags 'tag 1', 'tag 2' to (or from) existing tags
678 of bookmark at index 15012014:
679 buku -u 15012014 --tag + tag 1, tag 2
681 buku -u 15012014 --tag - tag 1, tag 2
682 32. Open URL at index 15012014 in browser:
684 buku -o 15012014
686 33. List bookmarks with no title or tags for bookkeeping:
688 buku -S blank
690 34. List bookmarks with immutable title:
692 buku -S immutable
694 35. Shorten the URL www.google.com and the URL at index 20:
696 buku --shorten www.google.com
698 buku --shorten 20
699 36. Append, remove tags at prompt (taglist index to the left, bookmark
701 index to the right):
702 // append tags at taglist indices 4 and 6-9 to existing tags in bookmarks at indices 5 and 2-3
704 buku (? for help) g 4 9-6 >> 5 3-2
705 // set tags at taglist indices 4 and 6-9 as tags in bookmarks at indices 5 and 2-3
706 buku (? for help) g 4 9-6 > 5 3-2
707 // remove all tags from bookmarks at indices 5 and 2-3
708 buku (? for help) g > 5 3-2
709 // remove tags at taglist indices 4 and 6-9 from tags in bookmarks at indices 5 and 2-3
710 buku (? for help) g 4 9-6 << 5 3-2
711 37. List bookmarks with colored output:
713 $ buku --colors oKlxm -p
715
717 Arun Prakash Jana <engineerarun@gmail.com>
718
720 https://github.com/jarun/buku
721
723 https://github.com/jarun/buku/wiki
724
726 https://github.com/jarun/buku/issues
727
729 Copyright © 2015-2021 Arun Prakash Jana <engineerarun@gmail.com>.
730 License GPLv3+: GNU GPL version 3 or later
732 <http://gnu.org/licenses/gpl.html>.
733 This is free software: you are free to change and redistribute it.
734 There is NO WARRANTY, to the extent permitted by law.
735Version 4.5 29 Dec 2020 BUKU(1)