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%kkmarks.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 - An auto-generated tag in the format 'YYYYMonDD' is added if
135 --tacit is not used in HTML, JSON, Markdown or Orgfile import.
136 10. Encryption is optional and manual. AES256 algorithm is used. To use
138 encryption, the database file should be unlocked (-k) before using
139 buku and locked (-l) afterwards. Between these 2 operations, the
140 database file lies unencrypted on the disk, and NOT in memory.
141 Also, note that the database file is unencrypted on creation.
142 11. Editor support:
144 - A single bookmark can be edited before adding. The editor can
145 be set using the environment variable *EDITOR* or by explicitly
146 specifying the editor. The latter takes precedence. If -a is used
147 along with -w, the details are populated in the editor template.
148 - In case of edit and update (a single bookmark), the existing
149 record details are fetched from DB and populated in the editor tem‐
150 plate. The environment variable EDITOR must be set. Note that -u
151 works independently of -w.
152 - All lines beginning with "#" will be stripped. Then line 1 will
153 be treated as the URL, line 2 will be the title, line 3 will be
154 comma separated tags, and the rest of the lines will be parsed as
155 descriptions.
156 12. Proxy support: please refer to the ENVIRONMENT section.
158
160 -a --add URL [tag, ...]
161 Bookmark URL along with comma-separated tags. A tag can have
162 multiple words.
163 -u --update [...]
165 Update fields of the bookmarks at specified indices in DB. If no
166 arguments are specified, all titles and descriptions are
167 refreshed from the web. Tags remain untouched. Works with update
168 modifiers for the fields url, title, tag and comment. If only
169 indices are passed without any edit options, titles and descrip‐
170 tions are fetched and updated (if not empty). Accepts hyphenated
171 ranges and space-separated indices. Updates search results when
172 used with search options, if no arguments.
173 -w --write [editor|index]
175 Edit a bookmark in editor before adding it. To edit and update
176 an existing bookmark, the index should be passed. However, in
177 this case the environment variable EDITOR must be set. The last
178 record is opened in EDITOR if index=-1.
179 -d --delete [...]
181 Delete bookmarks. Accepts space-separated list of indices (e.g.
182 5 6 23 4 110 45) or a single hyphenated range (e.g. 100-200).
183 Note that range and list don't work together. Deletes search
184 results when combined with search options, if no arguments.
185 -v --version
187 Show program version and exit.
188 -h --help
190 Show program help and exit.
191
193 --url [...]
194 Specify the URL, works with --update only. Fetches and updates
195 title if --title is not used.
196 --tag [+|-] [...]
198 Specify comma separated tags, works with --add, --update. Clears
199 the tags, if no arguments passed. Appends or deletes tags, if
200 list of tags is preceded by '+' or '-' respectively.
201 --title [...]
203 Manually specify the title, works with --add, --update. Omits or
204 clears the title, if no arguments passed.
205 -c --comment [...]
207 Add notes or description of the bookmark, works with --add,
208 --update. Clears the comment, if no arguments passed.
209 --immutable N
211 Set the title, description and tags of a bookmark immutable dur‐
212 ing autorefresh. Works with --add, --update. N=1 sets the
213 immutable flag, N=0 removes it. If omitted, bookmarks are added
214 with N=0.
215
217 -s --sany keyword [...]
218 Search bookmarks with ANY of the keyword(s) in URL, title or
219 tags and show the results. Prompts to enter result number to
220 open in browser. Note that the sequential result index is not
221 the DB index. The DB index is shown within '[]' after the title.
222 This is the default search option for positional arguments if no
223 other search option is specified.
224 -S --sall keyword [...]
226 Search bookmarks with ALL keywords in URL, title or tags and
227 show the results. Behaviour same as --sany.
228 Special keywords:
229 "blank": list entries with empty title/tag
230 "immutable": list entries with locked title
231 NOTE: To search the keywords, use --sany
232 --deep Search modifier to match substrings. Works with --sany, --sall.
234 -r --sreg expression
236 Scan for a regular expression match.
237 -t --stag [tag [,|+] ...] [- tag, ...]
239 Search bookmarks by tags.
240 Use ',' delimiter to find entries matching ANY of the tags
241 Use ' + ' delimiter to find entries matching ALL of the tags.
242 (Note that the ' + ' delimiter must be space separated)
243 NOTE: Cannot combine ',' and '+' in the same search
244 Use ' - ' to exclude bookmarks that match the tags that follow.
245 (Note that the '-' operator must be space separated).
246 List all tags alphabetically, if no arguments. The usage count
247 (number of bookmarks having the tag) is shown within first
248 brackets.
249 -x --exclude keyword [...]
251 Exclude bookmarks matching the specified keywords. Works with
252 --sany, --sall, --sreg and --stag.
253
255 -l --lock [N]
256 Encrypt (lock) the DB file with N (> 0, default 8) hash passes
257 to generate key.
258 -k --unlock [N]
260 Decrypt (unlock) the DB file with N (> 0, default 8) hash passes
261 to generate key.
262
264 --ai Auto-import bookmarks from Firefox, Google Chrome and Chromium
265 browsers.
266 -e --export file
268 Export bookmarks to Firefox bookmarks formatted HTML. Works with
269 all search options. Markdown is used if file has extension
270 '.md'.
271 Markdown format: [title](url), 1 entry per line. Orgfile is used
272 if file has extension '.org'
273 Orgfile format: * [[url][title]], 1 entry per line. A buku data‐
274 base is generated if file has extension '.db'.
275 -i --import file
277 Import bookmarks from Firefox bookmarks formatted HTML. file is
278 considered Firefox-exported JSON if it has '.md' extension,
279 Markdown (compliant with --export format) if it is '.md',
280 Orgfile if the extension is '.org' or another buku database if
281 the extension is '.db'.
282 -p --print [...]
284 Show details (DB index, URL, title, tags and comment) of book‐
285 mark record by DB index. If no arguments, all records with
286 actual index from DB are shown. Accepts hyphenated ranges and
287 space-separated indices. A negative value (introduced for conve‐
288 nience) behaves like the tail utility, e.g., -n shows the
289 details of the last n bookmarks.
290 -f --format N
292 Show selective monochrome output with specific fields. Works
293 with --print. Search results honour the option when used along
294 with --json. Useful for creating batch scripts.
295 N = 1, show only URL.
296 N = 2, show URL and tags in a single line.
297 N = 3, show only title.
298 N = 4, show URL, title and tags in a single line.
299 N = 5, show title and tags in a single line.
300 To omit DB index from printed results, use N0, e.g., 10, 20, 30,
301 40, 50.
302 -j --json
304 Output data formatted as JSON, works with --print output and
305 search results.
306 --colors COLORS
308 Set output colors. Refer to the COLORS section below for
309 details.
310 --nc Disable color output in all messages. Useful on terminals which
312 can't handle ANSI color codes or scripted environments.
313 -n --count N
315 Number of results to show per page (default 10).
316 --np Do not show the prompt, run and exit.
318 -o --open [...]
320 Open bookmarks by DB indices or ranges in browser. Open a random
321 index if argument is omitted.
322 --oa Open all search results immediately in the browser. Works best
324 with --np. When used along with --update or --delete, URLs are
325 opened in the browser first and then modified or deleted.
326 --replace old new
328 Replace old tag with new tag if both are passed; delete old tag
329 if new tag is not specified.
330 --shorten index|URL
332 Shorten the URL at DB index or an independent URL using the
333 tny.im URL shortener service.
334 --expand index|URL
336 Expand the URL at DB index or an independent URL shortened using
337 tny.im.
338 --cached index|URL
340 Browse the latest cached version of the URL at DB index or an
341 independent URL using the Wayback Machine. Useful for viewing
342 the content of bookmarks which are not live any more.
343 --suggest
345 Show a list of similar tags to choose from when adding a new
346 bookmark.
347 --tacit
349 Show lesser output. Reduces the verbosity of certain operations
350 like add, update etc.
351 --threads
353 Maximum number of parallel network connection threads to use
354 during full DB refresh. By default 4 connections are spawned. N
355 can range from 1 to 10.
356 -V Check the latest upstream version available. This is FYI. It is
358 possible the latest upstream released version is still not
359 available in your package manager as the process takes a while.
360 -z --debug
362 Show debug information and additional logs.
363
365 1-N Browse search results by indices and ranges.
366 O [id|range [...]]
368 Try to open search results or indices (when not in a search con‐
369 text) in a GUI browser. Toggle try to open urls in a GUI based
370 browser (even if BROWSER is set) if no arguments. Toggling is
371 useful when trying to open bookmarks by DB index.
372 a Open all search results in browser.
374 s keyword [...]
376 Search for records with ANY keyword.
377 S keyword [...]
379 Search for records with ALL keywords.
380 d Toggle deep search to match substrings ('pen' matches 'opened').
382 r expression
384 Run a regular expression search.
385 t [...]
387 Search bookmarks by a tag. List all tags alphabetically, if no
388 arguments.
389 g taglist id|range [...] [>>|>|<<] [record id|range ...]
391 Append, set, remove specific or all tags by indices and/or
392 ranges to bookmark indices and/or ranges (see EXAMPLES section
393 below). Search by space-separated taglist id(s) and/or range if
394 records are omitted.
395 o id|range [...]
397 Browse bookmarks by indices and/or ranges.
398 p id|range [...]
400 Print bookmarks by indices and/or ranges.
401 w [editor|id]
403 Edit and add or update a bookmark.
404 c id Copy url at search result index to clipboard.
406 ? Show help on prompt keys.
408 q, ^D, double Enter
410 Exit buku.
411
413 Completion scripts
414 Shell completion scripts for Bash, Fish and Zsh can be found in:
415 https://github.com/jarun/Buku/blob/master/auto-completion
416 BROWSER
418 Overrides the default browser. Refer to:
419 http://docs.python.org/library/webbrowser.html
420 EDITOR If defined, will be used as the editor to edit bookmarks with
422 option --write.
423 https_proxy
425 If defined, will be used to access http and https resources
426 through the configured proxy. Supported format:
427 http[s]://[username:password@]proxyhost:proxyport/
428 GUI integration
430 buku can be integrated in a GUI environment with simple tweaks.
431 Please refer to:
432 https://github.com/jarun/Buku/wiki/System-integration
433
435 buku allows you to customize the color scheme via a five-letter string,
436 reminiscent of BSD LSCOLORS. The five letters represent the colors of
437 - index
439 - title
440 - URL
441 - description/comment/note
442 - tag
443 respectively. The five-letter string is passed is as the argument to
445 the --colors option, or as the value of the environment variable
446 BUKU_COLORS.
447 We offer the following colors/styles:
449 ┌───────┬───────────────────────────────────────────────────┐
451 │Letter │ Color/Style │
452 ├───────├───────────────────────────────────────────────────┤
453 │a │ black │
454 │b │ red │
455 │c │ green │
456 │d │ yellow │
457 │e │ blue │
458 │f │ magenta │
459 │g │ cyan │
460 │h │ white │
461 │i │ bright black │
462 │j │ bright red │
463 │k │ bright green │
464 │l │ bright yellow │
465 │m │ bright blue │
466 │n │ bright magenta │
467 │o │ bright cyan │
468 │p │ bright white │
469 │A-H │ bold version of the lowercase-letter color │
470 │I-P │ bold version of the lowercase-letter bright color │
471 │x │ normal │
472 │X │ bold │
473 │y │ reverse video │
474 │Y │ bold reverse video │
475 └───────┴───────────────────────────────────────────────────┘
476 The default colors string is oKlxm, which stands for
478 - bright cyan index
480 - bold bright green title
481 - bright yellow URL
482 - normal description
483 - bright blue tag
484 Note that
486 - Bright colors (implemented as \x1b[90m - \x1b[97m) may not be
488 available in all color-capable terminal emulators;
489 - Some terminal emulators draw bold text in bright colors
491 instead;
492 - Some terminal emulators only distinguish between bold and
494 bright colors via a default-off switch.
495 Please consult the manual of your terminal emulator as well as
497 https://en.wikipedia.org/wiki/ANSI_escape_code for details.
498
501 1. Edit and add a bookmark from editor:
502 buku -w
504 buku -w 'gedit -w'
505 buku -w 'macvim -f' -a https://ddg.gg search engine, privacy
506 The first command picks editor from the environment variable
508 EDITOR. The second command opens gedit in blocking mode. The
509 third command opens macvim with option -f and the URL and
510 tags populated in template.
511 2. Add a bookmark with tags 'search engine' and 'privacy', com‐
513 ment 'Search engine with perks', fetch page title from the
514 web:
515 buku -a https://ddg.gg search engine, privacy -c Search engine with perks
517 In the output, >: url, +: comment, #: tags.
519 3. Add a bookmark with tags 'search engine' & 'privacy' and
521 immutable custom title 'DDG':
522 buku -a https://ddg.gg search engine, privacy --title 'DDG' --immutable 1
524 Note that URL must precede tags.
526 4. Add a bookmark without a title (works for update too):
528 buku -a https://ddg.gg search engine, privacy --title
530 5. Edit and update a bookmark from editor:
532 buku -w 15012014
534 This will open the existing bookmark's details in the editor
536 for modifications. Environment variable EDITOR must be set.
537 6. Update existing bookmark at index 15012014 with new URL,
539 tags and comments, fetch title from the web:
540 buku -u 15012014 --url http://ddg.gg/ --tag web search, utilities -c Private search engine
542 7. Fetch and update only title for bookmark at 15012014:
544 buku -u 15012014
546 8. Update only comment for bookmark at 15012014:
548 buku -u 15012014 -c this is a new comment
550 Applies to --url, --title and --tag too.
552 9. Export bookmarks tagged 'tag 1' or 'tag 2' to HTML, Mark‐
554 down, Orgfile or a new database:
555 buku -e bookmarks.html --stag tag 1, tag 2
557 buku -e bookmarks.md --stag tag 1, tag 2
558 buku -e bookmarks.org --stag tag 1, tag 2
559 buku -e bookmarks.db --stag tag 1, tag 2
560 All bookmarks are exported if search is not opted.
562 10. Import bookmarks from HTML, Markdown or Orgfile:
564 buku -i bookmarks.html
566 buku -i bookmarks.md
567 buku -i bookmarks.db
568 11. Delete only comment for bookmark at 15012014:
570 buku -u 15012014 -c
572 Applies to --title and --tag too. URL cannot be deleted
574 without deleting the bookmark.
575 12. Update or refresh full DB with page titles from the web:
577 buku -u
579 buku -u --tacit (show only failures and exceptions)
580 This operation can update the title or description fields of
582 non-immutable bookmarks by parsing the fetched page. Fields
583 are updated only if the fetched fields are non-empty. Tags
584 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
591 compact.
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
603 'debugging' in URL, title or tags:
604 buku kernel debugging
606 buku -s kernel debugging
607 17. Search bookmarks with ALL the keywords 'kernel' and 'debug‐
609 ging' in 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',
618 'debugging', 'general kernel concepts':
619 buku --stag kernel, debugging, general kernel concepts
621 20. Search for bookmarks matching ALL of the tags 'kernel',
623 'debugging', '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
629 both the tags 'kernel' and 'debugging', but excluding the
630 tags 'general 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)
647 to generate 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
656 20-30, 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) exist‐
678 ing tags 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,
701 bookmark 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-2019 Arun Prakash Jana <engineer‐
730 arun@gmail.com>.
731 License GPLv3+: GNU GPL version 3 or later
733 <http://gnu.org/licenses/gpl.html>.
734 This is free software: you are free to change and redistribute
735 it. There is NO WARRANTY, to the extent permitted by law.
736Version 4.2.2 02 May 2019 BUKU(1)