2016-04-22 09:09:20 -05:00
.TH "BUKU" "1" "Apr 2016" "Version 1.9" "User Commands"
2015-11-08 13:31:07 -06:00
.SH NAME
2016-03-25 11:39:45 -05:00
buku \- A private cmdline bookmark manager. Your mini web!
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 ]
2016-03-20 14:53:57 -05:00
.I [KEYWORDS ...]
2015-11-08 13:31:07 -06:00
.SH DESCRIPTION
2015-12-19 14:13:46 -06:00
.B buku
2016-03-20 14:14:13 -05:00
is a command-line tool to save, tag and search bookmarks.
2016-04-19 13:57:58 -05:00
.SH OPERATIONAL NOTES
2015-11-08 15:16:01 -06:00
.PP
2016-04-19 13:57:58 -05:00
The SQLite3 database file is stored in \fB $HOME/.local/share/buku/bookmarks.db\fR (or \fB $XDG_DATA_HOME/buku/bookmarks.db\fR , if XDG_DATA_HOME is defined) for each user. Before version 1.9,
2016-04-08 07:43:11 -05:00
.B buku
2016-04-08 11:00:54 -05:00
stored database in \fB $HOME/.cache/buku/bookmarks.db\fR . If the file exists, buku automatically moves it to new location.
2016-03-03 12:18:04 -06:00
.PP
2016-04-21 12:48:42 -05:00
The database index for entries starts from 1. Index 0 is used for special operations like show or refresh or delete all bookmarks.
.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
2016-03-25 09:12:49 -05:00
The same URL cannot be added twice. You can update tags and re-fetch title data. You can also insert a new bookmark at a free 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:
2016-04-19 14:08:39 -05:00
- Case-insensitive.
2016-04-19 13:32:28 -05:00
- 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 (see example).
2016-03-25 09:15:28 -05:00
- Search results are indexed serially. This index is different from actual database index of a bookmark record which is shown within '()' after the URL.
2015-12-19 12:15:22 -06:00
.PP
2016-04-20 10:41:07 -05:00
When a record is deleted, the last record is moved to the index.
.PP
2016-03-25 04:29:19 -05:00
AES256 is used for encryption. Optionally specify (-t) the number of hash iterations to use to generate key. Default is 8 iterations.
2015-12-19 12:15:22 -06:00
.PP
2016-04-10 08:01:11 -05:00
Encryption is optional and manual. 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.
2015-11-08 13:31:07 -06:00
.SH OPTIONS
.TP
2016-03-25 04:29:19 -05:00
.BI \- a " URL" " " "[tags]"
2015-11-08 15:16:01 -06:00
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
2016-04-20 10:41:07 -05:00
in DB (from -p 0 output). The last record is moved to the removed index.
2016-04-20 10:57:53 -05:00
.I N
= 0 deletes all records from DB.
2015-11-08 13:31:07 -06:00
.TP
2016-03-25 02:52:52 -05:00
.B \- e
Show all bookmarks with empty titles or no tags (for bookkeeping).
.TP
2016-03-16 13:03:15 -05:00
.B \- g
2016-04-10 08:01:11 -05:00
List all unique tags sorted alphabetically.
2016-03-16 13:03:15 -05:00
.TP
2015-11-08 15:16:01 -06:00
.BI \- i " N"
2016-03-25 09:12:49 -05:00
Add a new record at free index
2015-11-08 15:16:01 -06:00
.I N
2016-03-25 09:12:49 -05:00
in DB.
2015-11-10 05:20:30 -06:00
.TP
2016-03-23 07:23:35 -05:00
.B \- j
2016-04-20 10:09:18 -05:00
Output data formatted as json (works with -p and -s)
2016-03-23 07:23:35 -05:00
.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-25 13:23:26 -05:00
.BI \- m " title"
Manually specify the title, works with -a, -i, -u.
2016-03-03 12:18:04 -06:00
.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.
2016-04-20 10:09:18 -05:00
.I N
= 0 shows all records with actual index from DB. Shows URL, title and tags.
2015-11-08 13:31:07 -06:00
.TP
2015-11-08 15:16:01 -06:00
.BI \- s " keywords"
2016-04-19 13:32:28 -05:00
Search bookmarks for any of the keywords in URL, title or tags 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"
2016-04-20 10:17:47 -05:00
Search bookmarks with all keywords in URL, title or tags 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
2016-03-25 04:29:19 -05:00
(> 0) hash iterations to generate key, works with -k, -l.
2015-12-22 12:33:22 -06:00
.TP
2016-04-21 12:48:42 -05:00
.BI \- u " N" " " "[URL]" " " "[tags]"
2016-04-22 00:11:11 -05:00
Update fields of bookmark at index
2015-11-08 15:16:01 -06:00
.I N
2016-04-22 00:11:11 -05:00
in DB. The first keyword, if available, is treated as the URL. If URL is omitted (and -m is not used) the title of entry at index
2016-04-21 12:48:42 -05:00
.I N
2016-04-22 00:11:11 -05:00
is refreshed from the web,
2016-04-21 12:48:42 -05:00
.I N
2016-04-22 00:11:11 -05:00
= 0 refreshes all titles.
2015-11-08 13:31:07 -06:00
.TP
2015-11-11 01:28:37 -06:00
.BI \- x " N"
2016-04-20 10:09:18 -05: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
2016-04-19 10:46:19 -05:00
search result in browser.
.TP
.BI "Enter"
Exit 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
2016-04-21 10:29:32 -05:00
\fB Add\fR a bookmark with \fB tags\fR 'linux news' and 'open source', \fB fetch page title\fR from the web:
.PP
.EX
.IP
.B buku -a http://tuxdiary.com linux news, open source
.PP
.IP 2 . 4
2016-04-21 10:37:11 -05:00
\fB Add\fR a bookmark with \fB manual title\fR 'Linux magazine' & tags 'linux news' and 'open source':
2016-03-18 13:44:33 -05:00
.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
2016-04-21 10:29:32 -05:00
.IP 3 . 4
2016-04-21 10:37:11 -05:00
\fB Add\fR a bookmark \fB without a title\fR (works for update and insert too):
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-04-21 10:29:32 -05:00
.B buku -a -m none http://tuxdiary.com linux news, open source
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 4 . 4
2016-04-21 22:12:17 -05:00
\fB Update\fR existing bookmark at index 15012014 with new URL and tags, fetch title from the web:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-04-21 22:12:17 -05:00
.B buku -u 15012014 http://tuxdiary.com/ linux news, open source, magazine
2016-03-19 12:57:37 -05:00
.EE
.PP
.IP "" 4
Tags are updated too. Original tags are removed.
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 5 . 4
2016-04-21 10:37:11 -05:00
\fB Update\fR or refresh \fB full DB\fR with page titles from the web:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-04-21 12:48:42 -05:00
.B buku -u 0
2016-03-19 12:57:37 -05:00
.EE
.PP
.IP "" 4
2016-04-21 22:18:18 -05:00
This operation does not modify the indexes, URLs or tags. Only titles, if non-empty, are refreshed. Any index other than 0 refreshes title for that index.
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 6 . 4
2016-03-18 13:44:33 -05:00
\fB Delete\fR bookmark at index 15012014:
.PP
.EX
.IP
.B buku -d 15012014
2016-03-20 00:59:06 -05:00
.EE
.PP
.IP "" 4
The last index is moved to the deleted index to keep the DB compact.
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 7 . 4
2016-03-18 13:44:33 -05:00
\fB Delete all\fR bookmarks:
.PP
.EX
.IP
2016-04-20 10:57:53 -05:00
.B buku -d 0
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 8 . 4
2016-03-18 13:44:33 -05:00
List \fB all unique tags\fR alphabetically:
.PP
.EX
.IP
.B buku -g
.PP
2016-04-21 10:29:32 -05:00
.IP 9 . 4
2016-03-18 13:44:33 -05:00
\fB Insert\fR a bookmark at index 15012014 (fails if index or URL exists in database):
.PP
.EX
.IP
2016-04-21 10:29:32 -05:00
.B buku -i 15012014 http://tuxdiary.com/about linux news, open source
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 10 . 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
2016-04-21 10:29:32 -05:00
.IP 11 . 4
2016-03-19 11:20:14 -05:00
\fB Delete a tag\fR from DB:
.PP
.EX
.IP
.B buku -r 'old tag'
.PP
2016-04-21 10:29:32 -05:00
.IP 12 . 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-04-21 10:29:32 -05:00
.IP 13 . 4
2016-03-18 13:44:33 -05:00
\fB Show all\fR bookmarks with real index from database:
.PP
.EX
.IP
2016-04-20 10:09:18 -05:00
.B buku -p 0
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 14 . 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-04-21 10:29:32 -05:00
.IP 15 . 4
2016-04-19 13:32:28 -05:00
\fB Search\fR bookmarks for \fB ANY\fR of the keywords \fB kernel\fR and \fB debugging\fR in URL, title or tags:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
.B buku -s kernel debugging
.PP
2016-04-21 10:29:32 -05:00
.IP 16 . 4
2016-04-20 10:17:47 -05:00
\fB Search\fR bookmarks with \fB ALL\fR the keywords \fB kernel\fR and \fB debugging\fR in URL, title or tags:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
.B buku -S kernel debugging
.PP
2016-04-21 10:29:32 -05:00
.IP 17 . 4
2016-04-19 12:30:06 -05:00
\fB Search\fR bookmarks tagged \fB general kernel concepts\fR :
.PP
.EX
.IP
2016-04-19 23:02:34 -05:00
.B buku -S ',general kernel concepts,'
2016-04-19 12:30:06 -05:00
.EE
.PP
.IP "" 4
Note the commas (,) before and after the tag.
.PP
2016-04-21 10:29:32 -05:00
.IP 18 . 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.
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.