Provided by: buku_3.8+dfsg-1_all bug

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

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

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%kkmarks.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.
             -  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.
             - If indices are passed without any other options (--url, --title, --tag,  --comment
           and  --immutable),  read the URLs from DB and update titles 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.
             - An auto-generated tag in the format 'YYYYMonDD' is added if --tacit is not used in
           html, markdown or orgfile import.

       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.

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 are refreshed from the web. Works with update modifiers for
              the fields url, title, tag and comment. If only indices are passed without any edit
              options,  titles  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 of a bookmark immutable during updates. 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 and Chromium browsers.

       -e --export file
              Export bookmarks to Firefox bookmarks formatted HTML. Works with  --tag  to  export
              only specific tags. 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
              Markdown (compliant with --export format) if it has '.md' extension, 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
              To omit DB index from printed results, use N0, e.g., 10, 20, 30, 40.

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

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

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

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

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

       -z --debug
              Show debug information and additional logs.

PROMPT KEYS

       1-N    Browse search results by indices and ranges.

       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. The index
              of a tag from the tag list can be used to search all bookmarks having the tag. Note
              that multiple indices and/or ranges do not work with this key.

       o id|range [...]
              Browse bookmarks by indices and/or ranges.

       p id|range [...]
              Print bookmarks by indices and/or ranges.

       g [taglist id|range ...] [>>|>|<<] record id|range [...]
              Append,  set,  remove  specific  or  all  tags by indices and/or ranges to bookmark
              indices and/or ranges (see EXAMPLES section below).

       w [editor|id]
              Edit and add or update a bookmark.

       c id   Copy url at search result index to clipboard.

       O      Toggles ignore text-based browsers. If enabled, tries to open urls in a  GUI  based
              browser (even if BROWSER is set).

       ?      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  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.

       3.  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.

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

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

       5.  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.

       6.  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

       7.  Fetch and update only title for bookmark at 15012014:

              buku -u 15012014

       8.  Update only comment for bookmark at 15012014:

              buku -u 15012014 -c this is a new comment

           Applies to --url, --title and --tag too.

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

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

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

       10. Import bookmarks from HTML, markdown or orgfile:

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

       11. 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.

       12. Update or refresh full DB with page titles from the web:

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

           This operation does not modify the indexes, URLs, tags  or  comments.  Only  title  is
           refreshed if fetched title is non-empty.

       13. Delete bookmark at index 15012014:

              buku -d 15012014

           The last index is moved to the deleted index to keep the DB compact.

       14. Delete all bookmarks:

              buku -d

       15. Delete a range or list of bookmarks:

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

       16. Search  bookmarks  for  ANY  of the keywords 'kernel' and 'debugging' in URL, title or
           tags:

              buku kernel debugging
              buku -s kernel debugging

       17. Search bookmarks with ALL the keywords 'kernel' and 'debugging' in URL, title or tags:

              buku -S kernel debugging

       18. Search bookmarks tagged 'general kernel concepts':

              buku --stag general kernel concepts

       19. Search for bookmarks matching ANY of the tags 'kernel', 'debugging',  'general  kernel
           concepts':

              buku --stag kernel, debugging, general kernel concepts

       20. Search  for  bookmarks matching ALL of the tags 'kernel', 'debugging', 'general kernel
           concepts':

              buku --stag kernel + debugging + general kernel concepts

       21. 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'

       22. List all unique tags alphabetically:

              buku --stag

       23. Run a search and update the results:

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

       24. Run a search and delete the results:

              buku -s kernel debugging -d

       25. 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.

       26. Show details of bookmarks at index 15012014 and ranges 20-30, 40-50:

              buku -p 20-30 15012014 40-50

       27. Show details of the last 10 bookmarks:

              buku -p -10

       28. Show all bookmarks with real index from database:

              buku -p
              buku -p | more

       29. Replace tag 'old tag' with 'new tag':

              buku --replace 'old tag' 'new tag'

       30. Delete tag 'old tag' from DB:

              buku --replace 'old tag'

       31. 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

       32. Open URL at index 15012014 in browser:

              buku -o 15012014

       33. List bookmarks with no title or tags for bookkeeping:

              buku -S blank

       34. List bookmarks with immutable title:

              buku -S immutable

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

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

       36. 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

       37. List bookmarks with colored output:

              $ 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-2018 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.