Package: buku
bukubuku in action!Introductionbukuis a powerful bookmark manager and a personal textual mini-web.For those who prefer the GUI,bukuserverexposes a browsable front-end on a local web host server.When I started writing it, I couldn't find a flexible command-line solution with a private, portable, merge-able database along with seamless GUI integration. Hence,buku.bukucan import bookmarks from browser(s) or fetch the title, tags and description of a URL from the web. Use your favourite editor to add, compose and update bookmarks. Search bookmarks instantly with multiple search options, including regex and a deep scan mode (handy with URLs).It can look up broken links on Wayback Machine. There's an Easter Egg to revisit random bookmarks.There's no tracking, hidden history, obsolete records, usage analytics or homing.To get started right away, jump to theQuickstartsection.bukuhas one of the best documentation around. The man page comes with examples. For internal details, please refer to theoperational notes.bukuis a library too! There are several related projects, including a browser plug-in.Table of ContentsFeaturesInstallationDependenciesFrom a package managerRelease packagesFrom sourceRunning standaloneShell completionUsageCommand-line optionsColorsQuickstartExamplesAutomationTroubleshootingEditor integrationCollaboratorsContributionsRelated projectsIn the PressFeaturesStore bookmarks with auto-fetched title, tags and descriptionAuto-import from Firefox, Google Chrome, Chromium and MS EdgeOpen bookmarks and search results in browserShorten, expand URLs, browse cached page from Wayback MachineText editor integrationLightweight, clean interface, custom colorsPowerful search options (regex, substring...)Continuous search with on the fly mode switchPortable, merge-able database to sync between systemsImport/export bookmarks from/to HTML, XBEL, Markdown or OrgfileSmart tag management using redirection (>>, >, <<)Multi-threaded full DB refresh, manual encryption supportShell completion scripts, man page with examplesPrivacy-aware (no unconfirmed user data collection)InstallationDependenciesFeatureDependencyLang, SQLitePython 3.6+HTTPScertifi, urllib3EncryptioncryptographyHTMLbeautifulsoup4, html5libTo copy URL to clipboardbukuusesxsel(orxclip) on Linux,pbcopy(default installed) on OS X,clip(default installed) on Windows,termux-clipboardon Termux (terminal emulation for Android),wl-copyon Wayland. If X11 is missing, GNU Screen or tmux copy-paste buffers are recognized.From a package managerTo install buku with all its dependencies from PyPI, run:# pip3 install bukuYou can also installbukufrom your package manager. If the version available is dated try an alternative installation method.Packaging status (expand)Unlisted packagers:●PyPI(pip3 install buku)● Termux (pip3 install buku)Release packagesAuto-generated packages (with only the cli component) for Arch Linux, CentOS, Debian, Fedora, openSUSE Leap and Ubuntu are available with thelatest stable release.NOTE: CentOS may not have the python3-beautifulsoup4 package in the repos. Install it using pip3.From sourceIf you have git installed, clone this repository. Otherwise download thelatest stable releaseordevelopment version(risky).Install the dependencies. For example, on Ubuntu:$ apt-get install ca-certificates python3-urllib3 python3-cryptography python3-bs4Install the cli component to default location (/usr/local):$ sudo make installTo remove, run:$ sudo make uninstallPREFIXis supported, in case you want to install to a different location.Running standalonebukuis a standalone utility. From the containing directory, run:$ chmod +x buku
$ ./bukuShell completionShell completion scripts for Bash, Fish and Zsh can be found in respective subdirectories ofauto-completion/. Please refer to your shell's manual for installation instructions.UsageCommand-line optionsusage: buku [OPTIONS] [KEYWORD [KEYWORD ...]]

Bookmark manager like a text-based mini-web.

POSITIONAL ARGUMENTS:
      KEYWORD              search keywords

GENERAL OPTIONS:
      -a, --add URL [tag, ...]
                           bookmark URL with comma-separated tags
      -u, --update [...]   update fields of an existing bookmark
                           accepts indices and ranges
                           refresh title and desc if no edit options
                           if no arguments:
                           - update results when used with search
                           - otherwise refresh all titles and desc
      -w, --write [editor|index]
                           edit and add a new bookmark in editor
                           else, edit bookmark at index in EDITOR
                           edit last bookmark, if index=-1
                           if no args, edit new bookmark in EDITOR
      -d, --delete [...]   remove bookmarks from DB
                           accepts indices or a single range
                           if no arguments:
                           - delete results when used with search
                           - otherwise delete all bookmarks
      -h, --help           show this information and exit
      -v, --version        show the program version and exit

EDIT OPTIONS:
      --url keyword        bookmark link
      --tag [+|-] [...]    comma-separated tags
                           clear bookmark tagset, if no arguments
                           '+' appends to, '-' removes from tagset
      --title [...]        bookmark title; if no arguments:
                           -a: do not set title, -u: clear title
      -c, --comment [...]  notes or description of the bookmark
                           clears description, if no arguments
      --immutable N        disable web-fetch during auto-refresh
                           N=0: mutable (default), N=1: immutable

SEARCH OPTIONS:
      -s, --sany [...]     find records with ANY matching keyword
                           this is the default search option
      -S, --sall [...]     find records matching ALL the keywords
                           special keywords -
                           "blank": entries with empty title/tag
                           "immutable": entries with locked title
      --deep               match substrings ('pen' matches 'opens')
      -r, --sreg expr      run a regex search
      -t, --stag [tag [,|+] ...] [- tag, ...]
                           search bookmarks by tags
                           use ',' to find entries matching ANY tag
                           use '+' to find entries matching ALL tags
                           excludes entries with tags after ' - '
                           list all tags, if no search keywords
      -x, --exclude [...]  omit records matching specified keywords

ENCRYPTION OPTIONS:
      -l, --lock [N]       encrypt DB in N (default 8) # iterations
      -k, --unlock [N]     decrypt DB in N (default 8) # iterations

POWER TOYS:
      --ai                 auto-import (Firefox/Chrome/Chromium/Edge)
      -e, --export file    export bookmarks to Firefox format HTML
                           export XBEL, if file ends with '.xbel'
                           export Markdown, if file ends with '.md'
                           format: [title](url) <!-- TAGS -->
                           export Orgfile, if file ends with '.org'
                           format: *[[url][title]] :tags:
                           export buku DB, if file ends with '.db'
                           combines with search results, if opted
      -i, --import file    import bookmarks based on file extension
                           supports 'html', 'xbel', 'json', 'md', 'org', 'db'
      -p, --print [...]    show record details by indices, ranges
                           print all bookmarks, if no arguments
                           -n shows the last n results (like tail)
      -f, --format N       limit fields in -p or JSON search output
                           N=1: URL; N=2: URL, tag; N=3: title;
                           N=4: URL, title, tag; N=5: title, tag;
                           N0 (10, 20, 30, 40, 50) omits DB index
      -j, --json [file]    JSON formatted output for -p and search.
                           prints to stdout if argument missing.
                           otherwise writes to given file
      --colors COLORS      set output colors in five-letter string
      --nc                 disable color output
      -n, --count N        show N results per page (default 10)
      --np                 do not show the subprompt, run and exit
      -o, --open [...]     browse bookmarks by indices and ranges
                           open a random bookmark, if no arguments
      --oa                 browse all search results immediately
      --replace old new    replace old tag with new tag everywhere
                           delete old tag, if new tag not specified
      --shorten index|URL  fetch shortened url from tny.im service
      --expand index|URL   expand a tny.im shortened url
      --cached index|URL   browse a cached page from Wayback Machine
      --suggest            show similar tags when adding bookmarks
      --tacit              reduce verbosity, skip some confirmations
      --nostdin            do not wait for input (must be first arg)
      --threads N          max network connections in full refresh
                           default N=4, min N=1, max N=10
      -V                   check latest upstream version available
      -g, --debug          show debug information and verbose logs

SYMBOLS:
      >                    url
      +                    comment
      #                    tags

PROMPT KEYS:
    1-N                    browse search result indices and/or ranges
    O [id|range [...]]     open search results/indices in GUI browser
                           toggle try GUI browser if no arguments
    a                      open all results in browser
    s keyword [...]        search for records with ANY keyword
    S keyword [...]        search for records with ALL keywords
    d                      match substrings ('pen' matches 'opened')
    r expression           run a regex search
    t [tag, ...]           search by tags; show taglist, if no args
    g taglist id|range [...] [>>|>|<<] [record id|range ...]
                           append, set, remove (all or specific) tags
                           search by taglist id(s) if records are omitted
    n                      show next page of search results
    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 this help
    q, ^D, double Enter    exit bukuColorsbukusupports custom colors. Visit the wiki page on how tocustomize colorsfor more details.QuickstartExportVISUALorEDITORto point to your favourite editor. Note thatVISUALtakes precedence overEDITOR.Create a sweeter shortcut with some convenience.alias b='buku --suggest'Auto-import bookmarks from your browser(s). Please quit the relevant browsers beforehand to ensure the databases are not locked.b --aiManually add a bookmark (for hands-on).b -wList your bookmarks with DB index.b -pFor GUI and browser integration (or to sync bookmarks with your favourite bookmark management service) refer to the wiki page onSystem integration.Quick (bash/zsh) commands to fuzzy search with fzf and open the selection in Firefox:firefox $(buku -p -f 10 | fzf)
firefox $(buku -p -f 40 | fzf | cut -f1)POSIX script to show a preview of the bookmark as well:#!/usr/bin/env shurl=$(buku-p-f4|fzf-m--reverse--preview"buku -p {1}"--preview-window=wrap|cut-f2)if[-n"$url"];thenecho"$url"|xargsfirefoxfiExamplesEdit and adda bookmark from editor:$ buku -w
$ buku -w 'gedit -w'
$ buku -w 'macvim -f' -a https://ddg.gg search engine, privacyThe first command picks editor from the environment variableEDITOR. The second command opens gedit in blocking mode. The third command opens macvim with option -f and the URL and tags populated in template.Adda bookmark withtagssearch engineandprivacy,commentSearch engine with perks,fetch page titlefrom the web:$ buku -a https://ddg.gg search engine, privacy -c Search engine with perks
336. DuckDuckGo
> https://ddg.gg
+ Alternative search engine with perks
# privacy,search enginewhere, >: URL, +: comment, #: tagsAdda bookmark with tagssearch engine&privacyandimmutable custom titleDDG:$ buku -a https://ddg.gg search engine, privacy --title 'DDG' --immutable 1
336. DDG (L)
> https://ddg.gg
# privacy,search engineNote that URL must precede tags.Adda bookmarkwithout a title(works for update too):$ buku -a https://ddg.gg search engine, privacy --titleEdit and updatea bookmark from editor:$ buku -w 15012014This will open the existing bookmark's details in the editor for modifications. Environment variableEDITORmust be set.Updateexisting 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 engineFetch and update only titlefor bookmark at 15012014:$ buku -u 15012014Update only commentfor bookmark at 15012014:$ buku -u 15012014 -c this is a new commentApplies to --url, --title and --tag too.Exportbookmarks taggedtag 1ortag 2to 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 2All bookmarks are exported if search is not opted.Importbookmarks from HTML, XBEL, Markdown or Orgfile:$ buku -i bookmarks.html
$ buku -i bookmarks.xbel
$ buku -i bookmarks.md
$ buku -i bookmarks.org
$ buku -i bookmarks.dbDelete only commentfor bookmark at 15012014:$ buku -u 15012014 -cApplies to --title and --tag too. URL cannot be deleted without deleting the bookmark.Updateor refreshfull DBwith 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.Deletebookmark at index 15012014:$ buku -d 15012014
Index 15012020 moved to 15012014The last index is moved to the deleted index to keep the DB compact. Add--tacitto delete without confirmation.Delete allbookmarks:$ buku -dDeletearange or listof bookmarks:$ buku -d 100-200
$ buku -d 100 15 200Searchbookmarks forANYof the keywordskernelanddebuggingin URL, title or tags:$ buku kernel debugging
$ buku -s kernel debuggingSearchbookmarks withALLthe keywordskernelanddebuggingin URL, title or tags:$ buku -S kernel debuggingSearchbookmarkstaggedgeneral kernel concepts:$ buku --stag general kernel conceptsSearchfor bookmarks matchingANYof the tagskernel,debugging,general kernel concepts:$ buku --stag kernel, debugging, general kernel conceptsSearchfor bookmarks matchingALLof the tagskernel,debugging,general kernel concepts:$ buku --stag kernel + debugging + general kernel conceptsSearchfor bookmarks matching any of the keywordshelloorworld, excluding the keywordsrealandlife, matching both the tagskernelanddebugging, butexcludingthe tagsgeneral kernel conceptsandbooks:$ buku hello world --exclude real life --stag 'kernel + debugging - general kernel concepts, books'Listall unique tagsalphabetically:$ buku --stagRun asearch and updatethe results:$ buku -s kernel debugging -u --tag + linux kernelRun asearch and deletethe results:$ buku -s kernel debugging -dEncrypt or decryptDB withcustom number of iterations(15) to generate key:$ buku -l 15
$ buku -k 15The same number of iterations must be specified for one lock & unlock instance. Default is 8, if omitted.Show detailsof bookmarks at index 15012014 and ranges 20-30, 40-50:$ buku -p 20-30 15012014 40-50Show details of thelast 10 bookmarks:$ buku -p -10Show allbookmarks with real index from database:$ buku -p
$ buku -p | moreReplace tag'old tag' with 'new tag':$ buku --replace 'old tag' 'new tag'Delete tag'old tag' from DB:$ buku --replace 'old tag'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 2Open URLat index 15012014 in browser:$ buku -o 15012014List bookmarks withno title or tagsfor bookkeeping:$ buku -S blankList bookmarks withimmutable title:$ buku -S immutableShorten URLwww.google.comand the URL at index 20:$ buku --shorten www.google.com
$ buku --shorten 20Append, 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-2List bookmarks withcolored output:$ buku --colors oKlxm -pMorehelp:$ buku -h
$ man bukuAutomationInteractive workflows can be automated using expect. Issue#368has a working example on automating auto-import.TroubleshootingEditor integrationYou may encounter issues with GUI editors which maintain only one instance by default and return immediately from other instances. Use the appropriate editor option to block the caller when a new document is opened. See issue#210for gedit.CollaboratorsArun Prakash JanaRachmadani HaryonoJohnathan JenkinsSZ LinCopyright © 2015-2022Arun Prakash JanaContributionsMissing a feature? There's a rollingToDo Listwith identified tasks. Contributions are welcome! Please follow thePR guidelines.Related projectsbukubrow, WebExtension for browser integrationoil, search-as-you-type cli front-endbuku_run, rofi front-endpinku, a Pinboard-to-buku import utilitybuku-dmenu, a simple bash dmenu wrapperpoku, sync between Pocket and bukuEbuku, Emacs interface to bukudiigoku, buku importer for DiigoVideosBuku: Take Your Bookmarks Everywhere You GoBuku is a great open-source bookmark managerIn the Press2daygeekHacker MilkIt's F.O.S.S.LinOxideLinuxUser Magazine 01/2017 IssueMake Tech EasierOne Thing WellOpen Source For Youulno.net