2016-05-20 08:41:49 -05:00
.TH "BUKU" "1" "May 2016" "Version 2.1" "User Commands"
2015-11-08 13:31:07 -06:00
.SH NAME
2016-05-12 03:57:42 -05:00
buku \- A private command-line 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-05-22 18:36:41 -05:00
[-a URL [tags ...]] [-u [N]] [-i path] [-d [N]]
2016-04-30 23:33:21 -05:00
.br
2016-05-20 13:26:01 -05:00
[--url keyword] [--tag [...]] [-t [...]] [-c [...]]
2016-04-30 23:33:21 -05:00
.br
2016-05-18 12:23:08 -05:00
[-s keyword [...]] [-S keyword [...]] [--st [...]]
2016-04-30 23:33:21 -05:00
.br
[-k [N]] [-l [N]] [-p [N]] [-f N]
.br
2016-05-20 13:26:01 -05:00
[-r oldtag [newtag ...]] [-j] [-o N] [-z] [-h]
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-24 09:37:51 -05:00
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
2016-04-30 23:37:16 -05:00
- the \fB current directory\fR .
2016-04-24 09:37:51 -05:00
.PP
Before version 1.9,
2016-04-08 07:43:11 -05:00
.B buku
2016-04-24 09:37:51 -05:00
stored its 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
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
2016-04-27 12:07:19 -05: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-04-30 23:33:21 -05:00
URLs are unique in DB. The same URL cannot be added twice. You can update tags and re-fetch title data.
2016-05-20 13:26:01 -05:00
.pp
Update operation:
- if --title, --tag or --comment is passed without argument, clear the corresponding field from DB
- if --url is passed (and --title is omitted), update the title from web using the URL
- if index number is passed without any other options (--url, --title, --tag and --comment), read the URL from DB and update title from web
2015-11-10 01:58:37 -06:00
.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.
2016-05-18 12:23:08 -05:00
- --st : search bookmarks by tag, or show all tags alphabetically.
2016-05-17 21:48:27 -05:00
- You can search bookmarks by tag (see examples below).
2016-04-30 23:33:21 -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-05-17 03:20:20 -05:00
Auto DB compaction: when a record is deleted, the last record is moved to the index.
2016-04-20 10:41:07 -05:00
.PP
2016-04-30 23:33:21 -05:00
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.
2016-04-22 12:01:17 -05:00
.SH GENERAL OPTIONS
2015-11-08 13:31:07 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- a " " \- -add " URL [tags ...]"
2015-11-08 15:16:01 -06:00
Bookmark
.I URL
2016-05-18 22:24:46 -05:00
along with comma-separated tags. A tag can have multiple words.
2015-11-08 13:31:07 -06:00
.TP
2016-05-20 13:26:01 -05:00
.BI \- u " " \- -update " [N]"
2016-04-30 23:33:21 -05:00
Update fields of the bookmark at index
2015-11-08 13:31:07 -06:00
.I N
2016-05-20 13:26:01 -05:00
in DB. If
2016-04-30 23:33:21 -05:00
.I N
2016-05-21 12:29:41 -05:00
and other options are omitted, all titles are refreshed from the web. Works with update modifiers for the fields url, title, tag and comment. If only N is passed without any edit options, title is fetched and updated (if not empty).
2016-05-20 13:26:01 -05:00
.TP
2016-05-22 18:36:41 -05:00
.BI \- i " " \- -import " path"
Import bookmarks exported from Firefox, Google Chrome or IE in HTML format.
.TP
2016-05-20 13:46:44 -05:00
.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
2016-05-21 12:29:41 -05:00
.BI \- h " " \- -help
Show program help.
.SH EDIT OPTIONS
.TP
2016-05-20 13:26:01 -05:00
.BI \- -url " [...]"
2016-05-21 08:15:56 -05:00
Specify the URL, works with -u only. Fetches and updates title if --title is not used.
2016-05-20 13:26:01 -05:00
.TP
.BI \- -tag " [...]"
2016-05-21 02:13:34 -05:00
Specify comma separated tags, works with -a, -u. Clears the tags, if no arguments passed.
2016-03-16 13:03:15 -05:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- t " " \- -title " [...]"
2016-05-17 15:11:31 -05:00
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.
2016-04-30 23:33:21 -05:00
.SH SEARCH OPTIONS
2016-04-22 12:01:17 -05:00
.TP
2016-04-30 23:33:21 -05:00
.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 '[]'.
2015-11-10 05:20:30 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- S " " \- -sall " keyword [...]"
Search bookmarks with ALL keywords in URL, title or tags and show the results. Behaviour same as -s.
.br
2016-05-18 12:23:08 -05:00
Special keyword:
2016-04-30 23:33:21 -05:00
.br
"blank": list entries with empty title/tag
2016-05-18 11:06:54 -05:00
.TP
2016-05-18 12:23:08 -05:00
.BI \- -st " " \- -stag " [...]"
Search bookmarks by tag. List all tags alphabetically, if no arguments.
2016-04-30 23:33:21 -05:00
.SH ENCRYPTION OPTIONS
2016-03-23 07:23:35 -05:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- l " " \- -lock " [N]"
Encrypt (lock) the DB file with
.I N
(> 0, defualt 8) hash passes to generate key.
2015-12-19 12:15:22 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- k " " \- -unlock " [N]"
Decrypt (unlock) the DB file with
.I N
(> 0, defualt 8) hash passes to generate key.
.SH POWER OPTIONS
2015-12-19 12:15:22 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- p " " \- -print " [N]"
Show details (URL, title and tags) of bookmark record stored at index
2015-11-10 05:20:30 -06:00
.I N
2016-04-30 23:33:21 -05:00
in DB. If
.I N
is omitted, all records with actual index from DB are shown.
2015-11-08 13:31:07 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- f " " \- -format " N"
Show selective monochrome output. Works with -p. Useful for creating batch update scripts.
.br
2015-11-10 05:20:30 -06:00
.I N
2016-04-30 23:33:21 -05:00
= 1, only URL is shown.
.br
2016-04-20 10:09:18 -05:00
.I N
2016-04-30 23:33:21 -05:00
= 2, URL and tags are shown in a single line.
2015-11-08 13:31:07 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- r " " \- -replace " oldtag [newtag ...]"
2016-04-22 12:01:17 -05:00
Replace
.I oldtag
with
.I newtag
if both are passed, delete
.I oldtag
if
.I newtag
is omitted.
2015-11-08 13:31:07 -06:00
.TP
2016-05-15 04:41:37 -05:00
.BI \- j " " \- -json
2016-05-18 14:15:57 -05:00
Output data formatted as json, works with -p, -s, -S, --st.
2015-12-22 12:33:22 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- o " " \- -open " N"
Open URL at DB index
2015-11-11 01:28:37 -06:00
.I N
2016-04-30 23:33:21 -05:00
in browser.
2015-11-08 13:31:07 -06:00
.TP
2016-04-30 23:33:21 -05:00
.BI \- z " " \- -debug
Show debug information and additional logs.
2016-04-23 00:25:26 -05:00
.SH PROMPT 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-05-17 15:11:31 -05:00
\fB Add\fR a bookmark with \fB tags\fR 'linux news' and 'open source', \fB comment\fR 'Informative website on Linux and open source', \fB fetch page title\fR from the web:
2016-04-21 10:29:32 -05:00
.PP
.EX
.IP
2016-05-20 13:46:44 -05:00
.B buku -a https://tuxdiary.com linux news, open source -c Informative website on Linux and open source
In the output, >: title, +: comment, #: tags.
2016-04-21 10:29:32 -05:00
.PP
.IP 2 . 4
2016-04-30 23:33:21 -05:00
\fB Add\fR a bookmark with tags 'linux news' and 'open source' & \fB custom title\fR 'Linux magazine':
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-04-30 23:33:21 -05:00
.B buku -a http://tuxdiary.com linux news, open source -t 'Linux magazine'
2016-03-18 13:44:33 -05:00
.EE
.PP
.IP "" 4
2016-04-30 23:33:21 -05:00
Note that URL must precede tags.
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 3 . 4
2016-04-30 23:33:21 -05:00
\fB Add\fR a bookmark \fB without a title\fR (works for update too):
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-04-30 23:33:21 -05:00
.B buku -a http://tuxdiary.com linux news, open source -t
2016-03-18 13:44:33 -05:00
.PP
2016-04-21 10:29:32 -05:00
.IP 4 . 4
2016-05-20 13:46:44 -05:00
\fB Update\fR existing bookmark at index 15012014 with new URL, tags and comments, fetch title from the web:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-20 13:46:44 -05:00
.B buku -u 15012014 --url http://tuxdiary.com/ --tag linux news, open source, magazine -c site for Linux utilities
.PP
.IP 5 . 4
\fB Fetch and update only title\fR for bookmark at 15012014:
.PP
.EX
.IP
.B $ buku -u 15012014
.PP
.IP 6 . 4
\fB Update only comment\fR for bookmark at 15012014:
.PP
.EX
.IP
.B buku -u 15012014 -c this is a new comment
2016-03-19 12:57:37 -05:00
.EE
.PP
.IP "" 4
2016-05-20 13:46:44 -05:00
Applies to --url, --title and --tag too.
2016-03-18 13:44:33 -05:00
.PP
2016-05-20 13:46:44 -05:00
.IP 7 . 4
2016-05-22 18:36:41 -05:00
\fB Import\fR bookmarks:
.PP
.EX
.IP
.B buku -i bookmarks.html
.EE
.PP
.IP "" 4
HTML exports from Firefox, Google Chrome and IE are supported.
.PP
.IP 8 . 4
2016-05-20 13:46:44 -05:00
\fB Delete only comment\fR for bookmark at 15012014:
.PP
.EX
.IP
.B buku -u 15012014 -c
.EE
.PP
.IP "" 4
Applies to --title and --tag too. URL cannot be deleted without deleting the bookmark.
.PP
2016-05-22 18:36:41 -05:00
.IP 9 . 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-30 23:33:21 -05:00
.B buku -u
2016-03-19 12:57:37 -05:00
.EE
.PP
.IP "" 4
2016-05-20 13:26:01 -05:00
This operation does not modify the indexes, URLs, tags or comments. Only title is refreshed if fetched title is non-empty.
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 10 . 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-05-22 18:36:41 -05:00
.IP 11 . 4
2016-03-18 13:44:33 -05:00
\fB Delete all\fR bookmarks:
.PP
.EX
.IP
2016-04-30 23:33:21 -05:00
.B buku -d
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 12 . 4
2016-05-01 03:55:32 -05:00
\fB Search\fR bookmarks for \fB ANY\fR of the keywords 'kernel' and 'debugging' in URL, title or tags:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.B buku -s kernel debugging
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 13 . 4
2016-05-01 03:55:32 -05:00
\fB Search\fR bookmarks with \fB ALL\fR the keywords 'kernel' and 'debugging' in URL, title or tags:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.B buku -S kernel debugging
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 14 . 4
2016-05-01 03:55:32 -05:00
\fB Search\fR bookmarks with \fB tag\fR 'general kernel concepts':
2016-03-19 11:20:14 -05:00
.PP
.EX
.IP
2016-05-18 11:06:54 -05:00
.B buku --st general kernel concepts
2016-05-01 03:55:32 -05:00
.EE
.PP
.IP "" 4
Note the commas (,) before and after the tag. Comma is the tag delimiter in DB.
2016-03-19 11:20:14 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 15 . 4
2016-05-01 03:55:32 -05:00
List \fB all unique tags\fR alphabetically:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-18 12:23:08 -05:00
.B buku --st
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 16 . 4
2016-05-01 03:55:32 -05:00
\fB Encrypt or decrypt\fR DB with \fB custom number of iterations\fR (15) to generate key:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.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.
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 17 . 4
2016-05-01 03:55:32 -05:00
\fB Show details\fR of bookmark at index 15012014:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.B buku -p 15012014
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 18 . 4
2016-05-01 03:55:32 -05:00
\fB Show all\fR bookmarks with real index from database:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.B buku -p
2016-05-03 12:52:36 -05:00
.B buku -p | more
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 19 . 4
2016-05-01 03:55:32 -05:00
\fB Replace tag\fR 'old tag' with 'new tag':
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.B buku -r 'old tag' new tag
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 20 . 4
2016-05-01 03:55:32 -05:00
\fB Delete tag\fR 'old tag' from DB:
2016-04-19 12:30:06 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.B buku -r 'old tag'
2016-03-18 13:44:33 -05:00
.PP
2016-05-22 18:36:41 -05:00
.IP 21 . 4
2016-05-01 03:55:32 -05:00
\fB Open URL\fR at index 15012014 in browser:
2016-03-18 13:44:33 -05:00
.PP
.EX
.IP
2016-05-01 03:55:32 -05:00
.B buku -o 15012014
2016-05-23 01:21:29 -05:00
.PP
.IP 22 . 4
To list bookmarks with no title or tags for \fB bookkeeping\fR :
.PP
.EX
.IP
.B buku -S blank
2015-11-08 13:31:07 -06:00
.SH AUTHOR
2016-04-30 23:33:21 -05:00
Arun Prakash Jana <engineerarun@gmail.com>.
2015-11-08 13:31:07 -06:00
.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
2016-05-02 12:22:26 -05:00
.SH LICENSE
Copyright \(co 2015-2016 Arun Prakash Jana <engineerarun@gmail.com>.
2015-11-08 13:31:07 -06:00
.PP
2016-05-02 12:22:26 -05:00
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.