.TH "BUKU" "1" "May 2016" "Version 2.0" "User Commands"

.SH NAME

buku \- A private command-line bookmark manager. Your mini web!

.SH SYNOPSIS

.B buku

[-a URL [tags ...]] [-u [N [URL tags ...]]]

.br

[-t [...]] [-c [...]] [-d [N]] [-h]

.br

[-s keyword [...]] [-S keyword [...]] [--st [...]]

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

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

- --st : search bookmarks by tag, or show all tags alphabetically.

- You can search bookmarks by tag (see examples below).

- 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

Auto DB compaction: 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, -u. Omits or clears the title, if no arguments passed.

.TP

.BI \-c " " \--comment " [...]"

Add comment or description on the bookmark, works with -a, -u. Clears the comment, if no arguments passed.

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

.br

"blank": list entries with empty title/tag

.TP

.BI \--st " " \--stag " [...]"

Search bookmarks by tag. List all tags alphabetically, if no arguments.

.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 " " \--json

Output data formatted as json, works with -p, -s, -S, --st.

.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', \fBcomment\fR 'Informative website on Linux and open source', \fBfetch page title\fR from the web:

.PP

.EX

.IP

.B buku -a http://tuxdiary.com linux news, open source -c Informative website on Linux and 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

\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 9. 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 10. 4

\fBSearch\fR bookmarks with \fBtag\fR 'general kernel concepts':

.PP

.EX

.IP

.B buku --st general kernel concepts

.EE

.PP

.IP "" 4

Note the commas (,) before and after the tag. Comma is the tag delimiter in DB.

.PP

.IP 11. 4

List \fBall unique tags\fR alphabetically:

.PP

.EX

.IP

.B buku --st

.PP

.IP 12. 4

\fBEncrypt or decrypt\fR 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. Default is 8.

.PP

.IP 13. 4

\fBShow details\fR of bookmark at index 15012014:

.PP

.EX

.IP

.B buku -p 15012014

.PP

.IP 14. 4

\fBShow all\fR bookmarks with real index from database:

.PP

.EX

.IP

.B buku -p

.B buku -p | more

.PP

.IP 15. 4

\fBReplace tag\fR 'old tag' with 'new tag':

.PP

.EX

.IP

.B buku -r 'old tag' new tag

.PP

.IP 16. 4

\fBDelete tag\fR 'old tag' from DB:

.PP

.EX

.IP

.B buku -r 'old tag'

.PP

.IP 17. 4

\fBOpen URL\fR at index 15012014 in browser:

.PP

.EX

.IP

.B buku -o 15012014

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

Copyright \(co 2015-2016 Arun Prakash Jana <engineerarun@gmail.com>.

.PP

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.

.br

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.