buku/buku.1

.TH "BUKU" "1" "Apr 2016" "Version 1.9" "User Commands"
.SH NAME
buku \- A private cmdline bookmark manager. Your mini web!
.SH SYNOPSIS
.B buku
[-a URL [tags ...]] [-u [N [URL tags ...]]]
.br
     [-t [...]] [-d [N]] [-h]
.br
     [-s keyword [...]] [-S keyword [...]]
.br
     [-k [N]] [-l [N]] [-p [N]] [-f N]
.br
     [-r oldtag [newtag ...]] [-j] [-o N] [-z]
.SH DESCRIPTION
.B buku
is a command-line tool to save, tag and search bookmarks.
.SH OPERATIONAL NOTES
.PP
The SQLite3 database file is stored in:
  - \fB$XDG_DATA_HOME/buku/bookmarks.db\fR, if XDG_DATA_HOME is defined (first preference) or
  - \fB$HOME/.local/share/buku/bookmarks.db\fR, if HOME is defined (second preference) or
  - the \fBcurrent directory\fR, e.g. on Windows.
.PP
Before version 1.9,
.B buku
stored its database in \fB$HOME/.cache/buku/bookmarks.db\fR. If the file exists, buku automatically moves it to new location.
.PP
It's advisable to copy URLs directly from the browser address bar, i.e., along with the leading 'http://' or 'https://' token. buku looks up title data (found within <title></title> tags of HTML) from the web ONLY for fully-formed HTTP(S) URLs.
.PP
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 ('/") qoutes.
.PP
URLs are unique in DB. The same URL cannot be added twice. You can update tags and re-fetch title data.
.PP
Search works in mysterious ways:
  - Case-insensitive.
  - Substrings match ('match' matches 'rematched') for URL, title and tags.
  - -s : match any of the keywords in URL, title or tags.
  - -S : match all the keywords in URL, title or tags.
  - You can search bookmarks by tag (refer examples).
  - Search results are indexed serially. This index is different from actual database index of a bookmark record which is shown within '[]' after the URL.
.PP
When a record is deleted, the last record is moved to the index.
.PP
Encryption is optional and manual. AES256 algorithm is used. If you choose 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.
.SH GENERAL OPTIONS
.TP
.BI \-a " " \--add " URL [tags ...]"
Bookmark
.I URL
along with comma separated tags. A tag can have multiple words.
.TP
.BI \-u " " \--update " [N [URL tags ...]]"
Update fields of the bookmark at index
.I N
in DB. If URL is omitted (and -t is not used) the title of entry at index
.I N
is refreshed from the web. If
.I N
is omitted, all titles are refreshed from the web.
.TP
.BI \-t " " \--title " [...]"
Manually specify the title, works with -a, -i, -u. `-m none` clears title.
.TP
.BI \-d " " \--delete " [N]"
Delete bookmark at index
.I N
in DB (from -p output). The last record is moved to the removed index. If
.I N
is omitted, all records are deleted from the DB.
.TP
.BI \-h " " \--help
Show program help.
.SH SEARCH OPTIONS
.TP
.BI \-s " " \--sany " keyword [...]"
Search bookmarks for 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 in the end within '[]'.
.TP
.BI \-S " " \--sall " keyword [...]"
Search bookmarks with ALL keywords in URL, title or tags and show the results. Behaviour same as -s.
.br
Special keywords:
.br
"tags" : list all tags alphabetically
.br
"blank": list entries with empty title/tag
.SH ENCRYPTION OPTIONS
.TP
.BI \-l " " \--lock " [N]"
Encrypt (lock) the DB file with
.I N
(> 0, defualt 8) hash passes to generate key.
.TP
.BI \-k " " \--unlock " [N]"
Decrypt (unlock) the DB file with
.I N
(> 0, defualt 8) hash passes to generate key.
.SH POWER OPTIONS
.TP
.BI \-p " " \--print " [N]"
Show details (URL, title and tags) of bookmark record stored at index
.I N
in DB. If
.I N
is omitted, all records with actual index from DB are shown.
.TP
.BI \-f " " \--format " N"
Show selective monochrome output. Works with -p. Useful for creating batch update scripts.
.br
.I N
= 1, only URL is shown.
.br
.I N
= 2, URL and tags are shown in a single line.
.TP
.BI \-r " " \--replace " oldtag [newtag ...]"
Replace
.I oldtag
with
.I newtag
if both are passed, delete
.I oldtag
if
.I newtag
is omitted.
.TP
.BI \-j " " \--jason
Output data formatted as json (works with -p and -s)
.TP
.BI \-o " " \--open " N"
Open URL at DB index
.I N
in browser.
.TP
.BI \-z " " \--debug
Show debug information and additional logs.
.SH PROMPT KEYS
.TP
.BI "1-N"
Open
.I Nth
search result in browser.
.TP
.BI "Enter"
Exit buku.
.SH ENVIRONMENT
.TP
.BI BROWSER
Overrides the default browser. Ref:
.I http://docs.python.org/library/webbrowser.html
.SH EXAMPLES
.PP
.IP 1. 4
\fBAdd\fR a bookmark with \fBtags\fR 'linux news' and 'open source', \fBfetch page title\fR from the web:
.PP
.EX
.IP
.B buku -a http://tuxdiary.com linux news, open source
.PP
.IP 2. 4
\fBAdd\fR a bookmark with tags 'linux news' and 'open source' & \fBcustom title\fR 'Linux magazine':
.PP
.EX
.IP
.B buku -a http://tuxdiary.com linux news, open source -t 'Linux magazine'
.EE
.PP
.IP "" 4
Note that URL must precede tags.
.PP
.IP 3. 4
\fBAdd\fR a bookmark \fBwithout a title\fR (works for update too):
.PP
.EX
.IP
.B buku -a http://tuxdiary.com linux news, open source -t
.PP
.IP 4. 4
\fBUpdate\fR existing bookmark at index 15012014 with new URL and tags, fetch title from the web:
.PP
.EX
.IP
.B buku -u 15012014 http://tuxdiary.com/ linux news, open source, magazine
.EE
.PP
.IP "" 4
Tags are updated too. Original tags are removed.
.PP
.IP 5. 4
\fBUpdate\fR or refresh \fBfull DB\fR with page titles from the web:
.PP
.EX
.IP
.B buku -u
.EE
.PP
.IP "" 4
This operation does not modify the indexes, URLs or tags. Only title is refreshed if fetched title is non-empty.
.PP
.IP 6. 4
\fBDelete\fR bookmark at index 15012014:
.PP
.EX
.IP
.B buku -d 15012014
.EE
.PP
.IP "" 4
The last index is moved to the deleted index to keep the DB compact.
.PP
.IP 7. 4
\fBDelete all\fR bookmarks:
.PP
.EX
.IP
.B buku -d
.PP
.IP 8. 4
List \fBall unique tags\fR alphabetically:
.PP
.EX
.IP
.B buku -S tags
.PP
.IP 9. 4
\fBReplace tag\fR 'old tag' with 'new tag':
.PP
.EX
.IP
.B buku -r 'old tag' new tag
.PP
.IP 10. 4
\fBDelete tag\fR 'old tag' from DB:
.PP
.EX
.IP
.B buku -r 'old tag'
.PP
.IP 11. 4
\fBShow details\fR of bookmark at index 15012014:
.PP
.EX
.IP
.B buku -p 15012014
.PP
.IP 12. 4
\fBShow all\fR bookmarks with real index from database:
.PP
.EX
.IP
.B buku -p
.PP
.IP 13. 4
\fBOpen URL\fR at index 15012014 in browser:
.PP
.EX
.IP
.B buku -o 15012014
.PP
.IP 14. 4
\fBSearch\fR bookmarks for \fBANY\fR of the keywords 'kernel' and 'debugging' in URL, title or tags:
.PP
.EX
.IP
.B buku -s kernel debugging
.PP
.IP 15. 4
\fBSearch\fR bookmarks with \fBALL\fR the keywords 'kernel' and 'debugging' in URL, title or tags:
.PP
.EX
.IP
.B buku -S kernel debugging
.PP
.IP 16. 4
\fBSearch\fR bookmarks with \fBtag\fR 'general kernel concepts':
.PP
.EX
.IP
.B buku -S ',general kernel concepts,'
.EE
.PP
.IP "" 4
Note the commas (,) before and after the tag. Comma is the tag delimiter in DB.
.PP
.IP 17. 4
Encrypt/decrypt DB with \fBcustom number of iterations\fR (15) to generate key:
.PP
.EX
.IP
.B buku -l 15
.br
.B buku -k 15
.EE
.PP
.IP "" 4
The same number of iterations must be used for one lock & unlock instance.
.SH AUTHOR
Arun Prakash Jana <engineerarun@gmail.com>.
.SH HOME
.I https://github.com/jarun/buku
.SH REPORTING BUGS
.I https://github.com/jarun/buku/issues
.SH COPYRIGHT
Copyright \(co 2015 Arun Prakash Jana <engineerarun@gmail.com>.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
.PP
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.