'\" t
.\" Automatically generated by Pandoc 3.0.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "kpxhs" "1" "" "Version 1.11" "kpxhs manual"
.hy
.SH NAME
.PP
\f[B]kpxhs\f[R] - Interactive Keepass database TUI viewer
.SH SYNOPSIS
.PP
\f[B]kpxhs\f[R] [-h | --help] [-v | --version] [--write-config]
.SH DESCRIPTION
.PP
Interactive Keepass (https://keepass.info/) database TUI viewer.
The database and keyfile path can be configured to auto-fill on launch.
Entry details can be viewed and their username and password fields can
be copied to clipboard.
On exit, if the clipboard is \[lq]dirty\[rq] then it will offer to clear
it.
The clipboard can also be cleared after a configurable timeout, along
with a progress bar that counts down to clear.
.SH OPTIONS
.TP
\f[V]h, help\f[R]
Prints the help message and exit.
Ignores number of dashes.
.TP
\f[V]v, version\f[R]
Prints the version number and exit.
Ignores number of dashes.
.TP
\f[V]write-config\f[R]
Writes the default config.hs and theme.hs files to \[ti]/.config/kpxhs/.
Ignores number of dashes.
.SH KEYBINDINGS
.TP
\f[V]q\f[R]
Go up a directory, or attempt to quit if in root directory.
.TP
\f[V]Esc\f[R]
Focus or go back to browser (from entry details or search)
.TP
\f[V]Tab, Shift-Tab\f[R]
Cycle focus between elements in login fields and exit dialog
.TP
\f[V]Enter\f[R]
Show entry details of selected entry.
Attempts login if locked
.TP
\f[V]u\f[R]
Copy username of selected/current entry
.TP
\f[V]p\f[R]
Copy password of selected/current entry
.TP
\f[V][n]j, [n]s\f[R]
Move down the list by \[ga]n\[ga] items, default is 1.
\[ga]n\[ga] is an optional series of digits (0-9), that terminates when
\[ga]j\[ga] or \[ga]s\[ga] is pressed.
This resembles the vim motion commands.
Leading zeros are stripped.
For example, \[ga]4j\[ga] will move four items down and \[ga]10j\[ga]
will move ten items down.
Use the relative line numbers to help; the number shown is the exact
number needed for the digit \[ga]n\[ga]
.TP
\f[V][n]k, [n]w\f[R]
Move up the list by \[ga]n\[ga] items, default is 1.
\[ga]n\[ga] is an optional series of digits (0-9), that terminates when
\[ga]k\[ga] or \[ga]w\[ga] is pressed.
Leading zeros are stripped.
This resembles the vim motion commands.
For example, \[ga]4k\[ga] will move four items down and \[ga]10k\[ga]
will move ten items down.
Use the relative line numbers to help; the number shown is the exact
number needed for the digit \[ga]n\[ga]
.TP
\f[V]g\f[R]
Move to the top of the list
.TP
\f[V]G\f[R]
Move to the bottom of the list
.PP
The following table shows a summary of the keybindings and their effects
in each mode
.PP
.TS
tab(@);
lw(4.6n) lw(17.5n) lw(12.9n) lw(12.9n) lw(11.1n) lw(11.1n).
T{
Key
T}@T{
Browser
T}@T{
Search
T}@T{
Entry details
T}@T{
Login
T}@T{
Exit dialog
T}
_
T{
q
T}@T{
Go up dir or quit
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
T{
Esc
T}@T{
Clear command
T}@T{
Focus Browser
T}@T{
Back
T}@T{
Quit
T}@T{
-
T}
T{
/
T}@T{
Focus Search
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
T{
Tab
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
Cycle Focus
T}@T{
Cycle Focus
T}
T{
Enter
T}@T{
Show details
T}@T{
-
T}@T{
-
T}@T{
Unlock
T}@T{
-
T}
T{
j
T}@T{
Move down
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
T{
k
T}@T{
Move up
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
T{
u
T}@T{
Copy username
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
T{
p
T}@T{
Copy password
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
T{
g
T}@T{
Go to top
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
T{
G
T}@T{
Go to bottom
T}@T{
-
T}@T{
-
T}@T{
-
T}@T{
-
T}
.TE
.SH EXAMPLE USAGE
.IP "1." 3
\[ga]kpxhs\[ga]
.IP "2." 3
\[ga]YOUR_PASSWORD\[ga] (Assuming database path stored in config and no
keyfile)
.IP "3." 3
\[ga]/\[ga] (Focus search bar)
.IP "4." 3
\[ga]git\[ga] (Filter list to items with \[lq]git\[rq] in title)
.IP "5." 3
\[ga]Esc\[ga] (Focus to list)
.IP "6." 3
\[ga]j\[ga] (Focus one entry below)
.IP "7." 3
\[ga]p\[ga] (Copy password)
.IP "8." 3
\[ga]Esc\[ga] (quit)
.IP "9." 3
(Focus is on clear clipboard and exit by default) \[ga]Enter\[ga] (clear
clipboard and exit)
.SH CONFIGURATION
.SS INTRODUCTION
.PP
You can set the database and keyfile fields to be auto-filled with any
path, so you only need to enter your password on launch.
You can also customize the automatic clipboard clearing: change the
number of seconds to wait before clearing the clipboard; or disable the
feature altogether.
.PP
Hint: run \[ga]kpxhs \[en]write-config\[ga] to generate the default
config and theme for further editing
.SS SETTINGS
.PP
The config file is located in \[ga]\[ti]/.config/kpxhs/config.hs\[ga].
Make sure it is encoded as UTF-8.
Write something like:
.IP
.nf
\f[C]
Config { timeout = Just (Seconds 10)
       , dbPath = Just \[dq]/home/me/kpxhs/test/kpxhs_test.kdbx\[dq]
       , keyfilePath = Just \[dq]/home/me/kpxhs/test/keyfile.key\[dq]
       , focusSearchOnStart = Just False
       }
\f[R]
.fi
.PP
\f[B]It must be a valid Haskell expression\f[R] of a record with four
fields: timeout, dbPath, keyfilePath, and focusSearchOnStart.
All three are Maybe types - they are optional and you can always omit
specifying them by writing \[ga]Nothing\[ga].
Do not delete a field however, as it will result in an invalid config.
.PP
The paths can be any UTF-8 string; no validation is performed on them.
.SS timeout
.PP
After copying a username or password, \f[I]kpxhs\f[R] can automatically
clear the clipboard after a set number of seconds.
There are three valid values for the timeout field:
.TP
\f[V]Just (Seconds t)\f[R]
Set the number of seconds to wait for \[ga]t\[ga] seconds after the copy
for clearing the clipboard.
The number of seconds must be an integer.
.TP
\f[V]Just DoNotClear\f[R]
Disable automatic clipboard clearing.
.TP
\f[V]Nothing\f[R]
Fall back to the default, which is \f[B]10 seconds\f[R]
.SS dbPath
.PP
\f[I]kpxhs\f[R] can auto-fill the database path with a given string.
There are two valid values:
.TP
\f[V]Just \[dq]xxx\[dq]\f[R]
Fill in the database path with the string \[lq]xxx\[rq], without quotes.
.TP
\f[V]Nothing\f[R]
Fall back to the default, which is the empty string \[lq]\[rq]
.SS keyfilePath
.PP
\f[I]kpxhs\f[R] can auto-fill the keyfile path with a given string.
There are two valid values:
.TP
\f[V]Just \[dq]xxx\[dq]\f[R]
Fill in the keyfile path with the string \[lq]xxx\[rq], without quotes.
.TP
\f[V]Nothing\f[R]
Fall back to the default, which is the empty string \[lq]\[rq]
.SS focusSearchOnStart
.PP
Whether to focus the search bar after initial login, so \f[V]/\f[R] key
doesn\[cq]t have to be pressed to focus it.
There are two valid values:
.TP
\f[V]Just True\f[R]
Focus the search bar after initial login
.TP
\f[V]Just False\f[R]
Focus the browser list after initial login
.TP
\f[V]Nothing\f[R]
Fall back to the default, which is to focus the browser list after
initial login
.SS THEMING
.PP
The theme file is located in \[ga]\[ti]/.config/kpxhs/theme.hs\[ga].
Make sure it is encoded as UTF-8.
You should probably edit the default theme instead of writing from
scratch, because if you write from scratch, all the colors in the
default theme are lost.
.PP
This is the default theme if you don\[cq]t provide any:
.IP
.nf
\f[C]
[ ([\[dq]edit\[dq]],                          Val { fg = Black,  bg = White,  styles = [] })
, ([\[dq]edit\[dq],\[dq]focused\[dq]],                Val { fg = White,  bg = Blue,   styles = [] })
, ([\[dq]dialog\[dq]],                        Val { fg = White,  bg = Blue,   styles = [] })
, ([\[dq]button\[dq]],                        Val { fg = Black,  bg = White,  styles = [] })
, ([\[dq]button\[dq],\[dq]selected\[dq]],             Val { fg = Def,    bg = Yellow, styles = [] })
, ([\[dq]progressComplete\[dq]],              Val { fg = White,  bg = Blue,   styles = [] })
, ([\[dq]kpxhs\[dq],\[dq]key\[dq]],                   Val { fg = Def,    bg = White,  styles = [] })
, ([\[dq]kpxhs\[dq],\[dq]label\[dq]],                 Val { fg = Black,  bg = Def,    styles = [] })
, ([\[dq]kpxhs\[dq],\[dq]line_number\[dq]],           Val { fg = Yellow, bg = Def,    styles = [] })
, ([\[dq]kpxhs\[dq],\[dq]line_number\[dq],\[dq]focused\[dq]], Val { fg = Red,    bg = Def,    styles = [Bold]})
, ([\[dq]kpxhs\[dq],\[dq]list_border\[dq]],           Val { fg = Black,  bg = Def,    styles = [] })
, ([\[dq]kpxhs\[dq],\[dq]list_border\[dq],\[dq]focused\[dq]], Val { fg = Blue,   bg = Def,    styles = [] })
, ([\[dq]kpxhs\[dq],\[dq]directory\[dq]],             Val { fg = Black,  bg = Def,    styles = [Bold]})
, ([\[dq]kpxhs\[dq],\[dq]directory\[dq],\[dq]focused\[dq]],   Val { fg = Red,    bg = Def,    styles = [Bold]})
, ([\[dq]kpxhs\[dq],\[dq]go_up\[dq]],                 Val { fg = Green
                                          , bg = Def
                                          , styles = [Bold, Italic]
                                          })
, ([\[dq]kpxhs\[dq],\[dq]go_up\[dq],\[dq]focused\[dq]],       Val { fg = Blue
                                          , bg = Def
                                          , styles = [Bold, Italic]
                                          })
, ([\[dq]kpxhs\[dq],\[dq]entry\[dq]],                 Val { fg = Black,  bg = Def,    styles = [] })
, ([\[dq]kpxhs\[dq],\[dq]entry\[dq],\[dq]focused\[dq]],       Val { fg = Red,    bg = Def,    styles = [] })
]
\f[R]
.fi
.PP
\f[B]The theme file must be a valid Haskell expression\f[R].
It is a list-of-2-tuples; for every tuple, the first item is a
list-of-strings representing the attribute name, and the second item is
the attribute value.
The attribute value is represented as a record with three fields: fg,
bg, and styles.
The fg and bg fields only accept certain color names.
styles is a list-of-styles, and also only accept certain style names.
.SS Attribute names
.TP
\f[V][\[dq]xxx\[dq], \[dq]yyy\[dq]]\f[R]
Represents an attribute name \[lq]xxx.yyy\[rq].
Must have at least one item.
.PP
There are a few special attribute names exclusive to \f[I]kpxhs\f[R].
They are appropriately namespaced with \[ga]\[lq]kpxhs\[rq]\[ga].
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]key\[dq]]\f[R]
The key being bound (eg, \[lq]Esc\[rq])
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]label\[dq]]\f[R]
The label bound (eg, \[lq]exit\[rq])
.PP
In other words, the footer shows a nano-like grid of keys and their
action.
For example, \[lq]Esc exit\[rq] to indicate that pressing the Esc key
will exit.
\[ga]kpxhs.key\[ga] would style the \[lq]Esc\[rq] text and
\[ga]kpxhs.label\[ga] would style the \[lq]exit\[rq] text
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]line_number\[dq]]\f[R]
The relative line numbers on the left side of the list, for entries that
are not selected/in focus
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]line_number\[dq], \[dq]focused\[dq]]\f[R]
The relative line numbers on the left side of the list for the currently
selected entry
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]list_border\[dq]]\f[R]
The list/browser border when it is not focused (ie, focus is on search
bar).
Only foreground color is used.
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]list_border\[dq], \[dq]focused\[dq]]\f[R]
The list/browser border when it is focused (ie, focus is on list).
Only foreground color is used.
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]directory\[dq]]\f[R]
A directory that is not currently selected
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]directory\[dq], \[dq]focused\[dq]]\f[R]
A directory that is currently selected
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]go_up\[dq]]\f[R]
The \[lq]-- (Go up directory) --\[rq] text when it is not
focused/selected
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]go_up\[dq], \[dq]focused\[dq]]\f[R]
The \[lq]-- (Go up directory) --\[rq] text when it is focused/selected
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]entry\[dq]]\f[R]
An entry that is not currently selected
.TP
\f[V][\[dq]kpxhs\[dq], \[dq]entry\[dq], \[dq]focused\[dq]]\f[R]
An entry that is currently selected
.PP
Apart from those, you can use any other attribute name of elements used
in the program.
Here are the Brick docs for the attribute names of the elements used in
\f[I]kpxhs\f[R]:
.IP \[bu] 2
List
widget (https://hackage.haskell.org/package/brick-0.64/docs/Brick-Widgets-List.html#g:7)
.IP \[bu] 2
Exit
dialog (https://hackage.haskell.org/package/brick-0.64/docs/Brick-Widgets-Dialog.html#g:4)
.IP \[bu] 2
Login
dialog (https://hackage.haskell.org/package/brick-0.64/docs/Brick-Widgets-Edit.html#g:7)
.IP \[bu] 2
Progress
bar (https://hackage.haskell.org/package/brick-0.64/docs/Brick-Widgets-ProgressBar.html#g:1)
.IP \[bu] 2
Borders (https://hackage.haskell.org/package/brick-0.64/docs/Brick-Widgets-Border.html#g:5)
.SS Attribute values
.PP
The record has three fields:
.TP
\f[V]fg\f[R]
Set the foreground color.
See \f[B]Colors\f[R]
.TP
\f[V]bg\f[R]
Set the background color.
See \f[B]Colors\f[R]
.TP
\f[V]styles\f[R]
Set the given styles.
See \f[B]Styles\f[R]
.SS Colors
.TP
\f[V]Black, Red, Green, Yellow, Blue, Magenta, Cyan, White, BrightBlack, BrightRed, BrightGreen, BrightYellow, BrightBlue, BrightMagenta, BrightCyan, BrightWhite\f[R]
Set the color to one of those 16 colors.
Their exact values are configured through your terminal
.TP
\f[V]Def\f[R]
Use the default color for that element.
Essentially means a color is not specified
.TP
\f[V]RGB r g b\f[R]
Use an RGB color given by the three integers, from 0 to 255 inclusive.
Note that Brick doesn\[cq]t support the entire rgb palette, so some
colors can throw an error.
\f[I]kpxhs\f[R] allows it to be thrown, because some attributes might be
a hassle to navigate to, so aborting the program will let the user know
their color is invalid as early as possible.
.SS Styles
.TP
\f[V]Standout, Underline, ReverseVideo, Blink, Dim, Bold, Italic, Strikethrough\f[R]
Formats the text with the given style
.PP
If you don\[cq]t want to specify a style, leave the list empty.
.SS Theme examples
.IP "0." 3
Set the text of \[ga]kpxhs.key\[ga] to bold
.IP
.nf
\f[C]
, ([\[dq]kpxhs\[dq],\[dq]key\[dq]],       Val { fg = Def,   bg = Def,  styles = [Bold] } )
\f[R]
.fi
.IP "1." 3
Set the background color of \[ga]kpxhs.key\[ga] to red
.IP
.nf
\f[C]
, ([\[dq]kpxhs\[dq],\[dq]key\[dq]],       Val { fg = Def,   bg = Red,  styles = [] } )
\f[R]
.fi
.IP "2." 3
Set the background color of \[ga]kpxhs.key\[ga] to red and make it bold
.IP
.nf
\f[C]
, ([\[dq]kpxhs\[dq],\[dq]key\[dq]],       Val { fg = Def,   bg = Red,  styles = [Bold] } )
\f[R]
.fi
.IP "3." 3
Set the background color of \[ga]kpxhs.key\[ga] to red and make it
bold-italic
.IP
.nf
\f[C]
, ([\[dq]kpxhs\[dq],\[dq]key\[dq]],       Val { fg = Def,   bg = Red,  styles = [Bold, Italic] } )
\f[R]
.fi
.IP "4." 3
Set the background color of \[ga]kpxhs.key\[ga] to red, the foreground
color to RGB(51, 187, 204) and make it bold-italic
.IP
.nf
\f[C]
, ([\[dq]kpxhs\[dq],\[dq]key\[dq]],       Val { fg = RGB 51 187 204,   bg = Red,  styles = [Bold, Italic] } )
\f[R]
.fi
.SS CONFIGURATION NOTES
.PP
The only contents of the config and theme files is the single
expression; assignments, imports, statements, and comments are not
allowed.
You cannot use \[ga]$\[ga] to replace parenthesis, because no arbitrary
functions are evaluated.
Whitespace and newline rules follow normal Haskell rules for
expressions.
The config and theme files are not valid Haskell modules that can be
compiled; they are interpreted at launch.
.PP
Any records must match their specified number of fields; omission or
addition of any fields will result in an invalid config, and the default
will be used instead.
.PP
Type constructors must be written verbatim with no changes in
capitalization.
They include: \[ga]Just\[ga], \[ga]Nothing\[ga], \[ga]Seconds\[ga],
\[ga]DoNotClear\[ga], \[ga]Val\[ga], all the color names (eg,
\[ga]Red\[ga]), and all the style names (eg, \[ga]Bold\[ga])
.SH ENVIRONMENT
.PP
Requires keepassxc (https://github.com/keepassxreboot/keepassxc/)
installed with \[ga]keepassxc-cli\[ga] in PATH.
.SH FILES
.TP
\f[V]Configuration\f[R]
\[ga]\[ti]/.config/kpxhs/config.hs\[ga]
.TP
\f[V]Theme\f[R]
\[ga]\[ti]/.config/kpxhs/theme.hs\[ga]
.SH BUGS
.PP
The issue tracker and repo is in:
<https://github.com/akazukin5151/kpxhs>
.SH LICENSE
.PP
GPLv3 or later
.SH SEE ALSO
.PP
keepassxc-cli(1)