2016-03-19 12:21:21 -05:00
.TH "BUKU" "1" "Mar 2016" "Version 1.8" "User Commands"
2015-11-08 13:31:07 -06:00
.SH NAME
2015-12-19 14:13:46 -06:00
buku \- Bookmark manager. Your private Google.
2015-11-08 13:31:07 -06:00
.SH SYNOPSIS
2015-12-19 14:13:46 -06:00
.B buku
2016-03-03 12:18:04 -06:00
.I OPTIONS
.RI [ URL ]
.RI [ TAGS ]
2015-11-08 13:31:07 -06:00
.SH DESCRIPTION
2015-12-19 14:13:46 -06:00
.B buku
2015-11-08 13:31:07 -06:00
is a command line tool to save and search bookmarks.
2015-11-08 15:16:01 -06:00
.PP
2015-11-08 16:20:54 -06:00
The SQLite3 database file is stored in $HOME/.cache/bookmarks.db for each user.
2015-11-10 01:58:37 -06:00
.SH OPERATIONAL NOTES
2016-03-03 12:18:04 -06:00
URL must precede the tags. Manual title with multiple keywords must be within quotes.
.PP
2015-12-19 14:13:46 -06:00
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.
2015-11-08 15:16:01 -06:00
.PP
2015-11-10 01:58:37 -06:00
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.
2015-11-08 15:16:01 -06:00
.PP
2015-11-10 01:58:37 -06:00
The same URL cannot be added twice. You can update tags and re-fetch title data. You can also delete it and insert at the same index.
2015-11-08 15:16:01 -06:00
.PP
2015-11-10 01:58:37 -06:00
You can either add or update or delete record(s) in one instance. A combination of these operations is not supported in a single run.
.PP
Search works in mysterious ways:
2015-11-11 06:23:03 -06:00
- Substrings match ('match' matches 'rematched') for URL, tags and title.
- All the keywords are treated together as a 'single' tag in the 'same order'. Bookmarks with partial or complete tag matches are shown in results.
- '-s' : match any of the keywords in URL or title. Order is irrelevant.
- '-S' : match all the keywords in URL or title. Order is irrelevant.
- Search results are indexed serially. This index is different from actual database index of a bookmark reord which is shown within '()' after the URL.
2015-12-19 12:15:22 -06:00
.PP
2015-12-22 12:33:22 -06:00
Encryption support is manual. Database file should be unlocked ('-k') before using buku and locked ('-l') afterwards. Note that the database file is unecrypted on creation. AES256 is used for encryption. Optionally specify ('-t') the number of hash iterations to use to generate key. Default is 8 iterations.
2015-11-08 13:31:07 -06:00
.SH OPTIONS
.TP
2015-11-08 15:16:01 -06:00
.BI \- a " URL" " " "tag 1" , " tag 2" , " ..."
Bookmark
.I URL
2015-11-08 17:51:25 -06:00
along with comma separated tags. A tag can have multiple words. The same URL cannot be added twice.
2015-11-08 13:31:07 -06:00
.TP
2015-11-08 15:16:01 -06:00
.BI \- d " N"
Delete bookmark at index
2015-11-08 13:31:07 -06:00
.I N
2015-11-11 06:23:03 -06:00
in DB (from '-P' output).
2015-11-08 13:31:07 -06:00
.TP
2015-11-08 15:16:01 -06:00
.B \- D
Delete ALL bookmarks.
2015-11-08 13:31:07 -06:00
.TP
2016-03-16 13:03:15 -05:00
.B \- g
Show all unique tags sorted aplhabetically.
.TP
2015-11-08 15:16:01 -06:00
.BI \- i " N"
Add a new record at index
.I N
2015-11-10 05:20:30 -06:00
in DB. Use this option to fill blank indices left by deleted bookmarks.
.TP
2015-12-19 12:15:22 -06:00
.B \- k
Decrypt (unlock) the DB file.
.TP
.B \- l
Encrypt (lock) the DB file.
.TP
2016-03-03 12:18:04 -06:00
.BI \- m " keywords"
Add or update the title manually.
.TP
2015-11-10 05:20:30 -06:00
.BI \- o " N"
Open URL at DB index
.I N
in browser.
2015-11-08 13:31:07 -06:00
.TP
2015-11-09 12:32:10 -06:00
.BI \- p " N"
2015-11-10 05:20:30 -06:00
Show details of bookmark record stored at index
.I N
in DB.
2015-11-09 12:32:10 -06:00
.TP
.B \- P
2015-11-11 06:23:03 -06:00
Show all bookmark records from the DB along with actual index. Shows URL, title and tags.
2015-11-08 13:31:07 -06:00
.TP
2015-11-13 05:12:12 -06:00
.B \- R
Refresh all bookmarks. Titles are fetched from the web. Tags are retained.
.TP
2015-11-08 15:16:01 -06:00
.BI \- s " keywords"
2015-11-11 06:23:03 -06:00
Search bookmarks for a (partial) tag or any keyword and show the results. Prompts to enter result number to open in browser. Note that the sequential index number may not match the real index in database. DB index is shown in the end within '()'.
2015-11-11 06:04:57 -06:00
.TP
.BI \- S " keywords"
2015-11-11 06:23:03 -06:00
Search bookmarks for a (partial) tag or occurrence of all keywords in URL or title and show the results. Rest same as '-s'.
2015-11-08 13:31:07 -06:00
.TP
2015-12-22 12:33:22 -06:00
.BI \- t " N"
Use
.I N
(> 0) hash iterations to generate key, works with '-k', '-l'.
.TP
2015-11-08 15:16:01 -06:00
.BI \- u " N"
Update bookmark at index
.I N
2015-11-10 05:20:30 -06:00
in DB.
2015-11-08 13:31:07 -06:00
.TP
2015-11-10 02:31:35 -06:00
.BI \- w
2015-11-11 06:23:03 -06:00
Fetch title data from the web. Works with '-a', '-i' or '-u' options.
2015-11-10 02:31:35 -06:00
.TP
2015-11-11 01:28:37 -06:00
.BI \- x " N"
2015-11-11 06:23:03 -06:00
Show selective monochrome output. Works with '-P'. If
2015-11-11 01:28:37 -06:00
.I N
= 1, only URL is shown. If
.I N
= 2, URL and tags are shown in a single line. Useful for creating batch update scripts.
.TP
2015-11-08 15:16:01 -06:00
.BI \- z
2015-11-08 13:31:07 -06:00
Enable debugging.
.TP
2015-11-08 15:16:01 -06:00
.BI ""
2015-12-19 14:13:46 -06:00
Any other option shows help and exits buku.
2015-11-08 15:16:01 -06:00
.SH KEYS
2015-11-08 13:31:07 -06:00
.TP
.BI "1-N"
2015-11-08 15:16:01 -06:00
Open
.I Nth
2015-12-19 14:13:46 -06:00
search result in browser. Pressing 'Enter' exits buku.
2015-11-08 13:31:07 -06:00
.SH ENVIRONMENT
.TP
.BI BROWSER
2015-11-08 15:16:01 -06:00
Overrides the default browser. Ref:
2015-11-08 13:31:07 -06:00
.I http://docs.python.org/library/webbrowser.html
2016-03-18 13:44:33 -05:00
.SH EXAMPLES
.PP
.IP 1 . 4
\fB Add\fR a new bookmark with title \fB Linux magazine\fR & tags \fB linux news\fR and \fB open source\fR :
.PP
.EX
.IP
.B buku -a -m 'Linux magazine' http://tuxdiary.com linux news, open source
.EE
.PP
.IP "" 4
Note that URL must precede tags. Multiple words in title must be within quotes. The assigned automatic index 15012014 is unique, one greater than highest index already in use in database.
.PP
.IP 2 . 4
Add a bookmark, \fB fetch page title\fR information from web:
.PP
.EX
.IP
.B buku -a -w http://tuxdiary.com linux news, open source
.PP
.IP 3 . 4
\fB Update\fR existing bookmark at index 15012014 with a new tag:
.PP
.EX
.IP
.B buku -u 15012014 -w http://tuxdiary.com linux news, open source, magazine
.PP
.IP 4 . 4
Update or \fB refresh full DB\fR :
.PP
.EX
.IP
.B buku -R
.PP
.IP 5 . 4
\fB Delete\fR bookmark at index 15012014:
.PP
.EX
.IP
.B buku -d 15012014
.PP
.IP 6 . 4
\fB Delete all\fR bookmarks:
.PP
.EX
.IP
.B buku -D
.PP
.IP 7 . 4
List \fB all unique tags\fR alphabetically:
.PP
.EX
.IP
.B buku -g
.PP
.IP 8 . 4
\fB Insert\fR a bookmark at index 15012014 (fails if index or URL exists in database):
.PP
.EX
.IP
.B buku -i 15012014 -w http://tuxdiary.com/about linux news, open source
.EE
.PP
.IP "" 4
This option is useful in filling deleted indices from database manually.
.PP
.IP 9 . 4
2016-03-19 11:20:14 -05:00
\fB Replace a tag\fR with new one:
.PP
.EX
.IP
.B buku -r 'old tag' 'new tag'
.PP
.IP 10 . 4
\fB Delete a tag\fR from DB:
.PP
.EX
.IP
.B buku -r 'old tag'
.PP
.IP 11 . 4
2016-03-18 13:44:33 -05:00
\fB Show info\fR on bookmark at index 15012014:
.PP
.EX
.IP
.B buku -p 15012014
.PP
2016-03-19 11:20:14 -05:00
.IP 12 . 4
2016-03-18 13:44:33 -05:00
\fB Show all\fR bookmarks with real index from database:
.PP
.EX
.IP
.B buku -P
.PP
2016-03-19 11:20:14 -05:00
.IP 13 . 4
2016-03-18 13:44:33 -05:00
\fB Open URL\fR at index 15012014 in browser:
.PP
.EX
.IP
.B buku -o 15012014
.PP
2016-03-19 11:20:14 -05:00
.IP 14 . 4
2016-03-18 13:44:33 -05:00
\fB Search\fR bookmarks for a tag matching \fB kernel debugging\fR or \fB ANY\fR of the keywords \fB kernel\fR and \fB debugging\fR in URL or title (separately):
.PP
.EX
.IP
.B buku -s kernel debugging
.PP
2016-03-19 11:20:14 -05:00
.IP 15 . 4
2016-03-18 13:44:33 -05:00
\fB Search\fR bookmarks for a tag matching \fB kernel debugging\fR or \fB ALL\fR the keywords \fB kernel\fR and \fB debugging\fR in URL or title (separately):
.PP
.EX
.IP
.B buku -S kernel debugging
.PP
2016-03-19 11:20:14 -05:00
.IP 16 . 4
2016-03-18 13:44:33 -05:00
Encrypt/decrypt DB with \fB custom number of iteration\fR to generate key:
.PP
.EX
.IP
.B buku -l -t 15
.PP
.EX
.IP
.B buku -k -t 15
.EE
.PP
.IP "" 4
The same number of iterations must be used for one lock & unlock instance.
.PP
2016-03-19 11:20:14 -05:00
.IP 17 . 4
2016-03-18 13:44:33 -05:00
Show \fB debug info\fR :
.PP
.EX
.IP
.B buku -z ...
2015-11-08 13:31:07 -06:00
.SH AUTHOR
Written by Arun Prakash Jana <engineerarun@gmail.com>.
.SH HOME
2015-12-19 14:13:46 -06:00
.I https://github.com/jarun/buku
2015-11-08 13:31:07 -06:00
.SH REPORTING BUGS
2015-12-19 14:13:46 -06:00
.I https://github.com/jarun/buku/issues
2015-11-08 13:31:07 -06:00
.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.