kpsh, or KeePass Shell, is a command line password manager working
directly with KeePass databases.
kpsh provides an interactive shell-like REPL environment in which
users may use various commands (see the "COMMANDS" section) to
access and modify KeePass databases. kpsh reads user input, evaluates it,
then prints responses. Shell can be closed by running exit command or
by pressing ctrl+d, which sends End of File (EOF) in most shells.
Alternatively kpsh may be started with one or --command
options. In this mode kpsh executes each command and then exists. This mode
of work is non-interactive. It means that kpsh won't prompt user for any
input, like a password to unlock a database. It should be provided in other
way (see the "OPTIONS" section).
kpsh may accept commands directly to its standard input, for
example by piping them to it. Many commands may be passed to kpsh by putting
each one in a separate line. This mode is non-interactive as well.
kpsh also implements a "daemon mode", enabled with
--daemon flag. In this mode kpsh waits for commands from external
clients and communicates directly with them (see kpsh-client(1) and
kpsh-menu(1)).
The only argument which kpsh accepts is DATABASE: a KeePass
database on which commands should be performed. It can be changed at any
time by running open command.
-h, --help
Show help message and quit.
--password PASSWORD
Plain text password to KeePass database. This option
is insecure. Passwords passed this way may be seen for example on a
process list and in the shell's command history. Users are encouraged to use
other methods of passing passwords, like --password-command. See the
"AUTOMATIC DATABASE UNLOCKING" section.
--password-command PASSWORD_COMMAND
Command whose output kpsh will use as a database
password. kpsh won't strip any characters from the command output.
Particularily, commands shouldn't print the ending new line character if it
isn't the part of password. You may pipe a command through
tr to strip
characters if it is necessary.
Commands are executed through a subshell started with a "sh
-c". It means that PASSWORD_COMMAND accepts any commands format
which shell would accept (for example command piping).
See also the "AUTOMATIC DATABASE UNLOCKING" section.
--keyfile KEYFILE
Key file for unlocking database.
--pinentry PROG
Path to pinentry program, which kpsh may use to
ask user for a password.
-c, --command COMMAND
Instead of starting interactive shell, kpsh will run one
or more commands and then exit. This option may be used several times, each
one for a separate command.
--prompt
Text used by shell for a prompt.
-d, --daemon
Instead of starting interactive shell, kpsh will run a
server which listens for commands from external clients and communicates
directly with them. Server listens on a UNIX socket given by a
-socket-path option.
-s, --socket-path
Path to the socket on which kpsh which runs in a daemon
mode listens. Default: $XDG_RUNTIME_DIR/kpsh.sock, but if
XDG_RUNTIME_DIR environment variable is not set, kpsh will fall back to
legacy /tmp/kpsh-$UID.sock.
add [options...] <path>
Add a new entry to the database if it doesn't exist yet.
Existing entries are not modified.
path reflects a group and a name
under which a new entry will be added. For example "some-group/foo"
creates an entry "foo" under "some-group" group.
If password is neither provided with --password option, nor
generated with --generate-password, kpsh will interactively ask user
to type it. Empty passwords are allowed.
Options:
-u, --username USERNAME
Set username for the new entry.
-p, --password PASSWORD
Set password for the new entry. Empty string (e.g. '' or
"") will unset a password.
-u, --url URL
Set URL for the new entry.
-n, --note NOTE
Add a note. One note takes one line. Many notes can be
added by using -n more than once.
-s, --autotype-sequence SEQUENCE
Set key sequence for autotyping. See
https://keepass.info/help/base/autotype.html for format
description.
-t, --property PROPERTY=VALUE
Set custom property named PROPERTY to the
VALUE. Spaces around name and value are preserved, so
"name=val" and "name = val" are different entries.
Password Generation:
-g, --generate-password
Enable interactive password generation when
--password is not set. By default password is generated from ASCII
letters and digits. New password must be accepted before it is saved.
-G, --generate-password-no-confirm
Same as --generate-password, but kpsh will
automatically save generated password, without any user confirmation.
--letters
Use ASCII letters in generated password: a-z, A-Z.
--digits
Use digits in generated password: 0-9.
--logograms
Use logograms in generated password: #$%&@^`~.
--punctuation
Use punctuation symbols in generated password: !#,.:;
etc...
--characters CHARACTERS
Specify characters set from which password should be
generated Setting this option overrides usage of --letters,
--digits and --punctuation.
-l, --length N
Set the length of generated password (default: 20).
autotype [options...] <path>
Auto-type sequence of entry fields. Auto-typing simulates
pressing keyboard keys to any currently open window.
autotype uses the
sequence defined for entry under the
path (see the
add
--autotype-sequence option). A different sequence may be requested with
--sequence option. In case neither of these sequences is available,
autotype will use the sequence defined by
--default option, or
the global default.
For auto-typing, autotype uses programs installed on a
system. Choice of used programs depends on detected environment:
xdotool for X11 environment and either wtype or ydotool
for Wayland (NOTE: only ydotool >= 1.0 is supported).
See also https://keepass.info/help/base/autotype.html
Options:
-s, --sequence SEQUENCE
Force kpsh to use the given SEQUENCE for auto
typing.
-d, --default DEFAULT_SEQUENCE
Change the auto-type sequence used when entry doesn't
have any specific auto-type sequence set.
-D, --delay DELAY
Delay beteen simulated keypresses.
-f, --force
Force auto-type for entries for which auto-type was
disabled.
-b, --backend BACKEND
Do not try to auto-detect the environment, but instead
force force usage of backend program for typing.
Accepted values for BACKEND are: xdotool,
ydotool, wtype.
-B, --backend-command BACKEND_COMMAND
Run a command which is used to detect the backend.
Command should print one of accepted backend names to the standard output (see
the --backend option)
clipboard [options...] <path>
<field>
Copy username or password
field from a database
entry to the system clipboard. Copied data will be automatically cleared after
a few seconds.
This command relies on external programs which should be installed
on a system:
Options:
-c, --clear-after SECS
Seconds after which clipboard will be cleared. Default:
10.
--no-clear
Don't clear the clipboard after copy.
db
Query opened database info.
delete [options...] <paths...>
Delete entries under
paths from a database.
Without
--recursive option each
path must point to the database
entry. With
--recursive,
paths may point to the groups, which
will be deleted, together with their contents.
Options:
-r, --recursive
Delete groups and their contents recursively.
echo <message>
Display a message.
edit [options...] <path>
Edit existing entry.
This command implements the same options as add command. On
top of them, it adds a few options of its own.
To set password securely, without leaving a trace on your screen,
use --askpass option.
Options (which not present in add command):
--askpass
Interactively ask for password. User input will be
hidden.
-N, --delete-notes NOTES
Delete note (line in notes). Notes are accessed by their
index (starting with 1 for the first note). Range of notes can be deleted by
passing e.g. "-N 2-4". Range specified this way is inclusive,
i.e. notes 2, 3 and 4 are removed. All notes can be removed by passing
"-N *".
exit
Exit kpsh.
help <command>
Show help for command.
lock
Lock current database. Besides disabling access to
database, locking of database also resets a PASSWORD,
PASSWORD_COMMAND and KEYFILE. Effectively, any unlock after
explicit database lock will have to be interactively authenticated.
ls [glob]
List contents of database. Entries may be filtered by
providing a glob expression, similar to glob expressions used by
shells. Supported special glob characters include "*", "?"
and "[]" character ranges.
move <source> <destination>
Move entry to the new path. destination path
musn't exist. All parent groups of destination are automatically
created if they don't exist yet.
open <file>
Change currently opened database. New database will be
created if it doesn't exist.
show <path> [fields...]
Show contents of entry. All available fields are printed
by default. Their list is narrowed by providing
fields arguments. In
case of
notes, each note (each line) is printed in a new line, together
with its index.
Supported fields are: path, username,
password, url, autotype_sequence, notes.
Additionally, if field is prefixed with p:, then a custom property
will be searched (for example "p:foo" shows the value of
"foo" custom property").
Options:
-n, --no-field-name
Hide field names in the output.
sleep <seconds>
Sleep for a given number of seconds. Seconds might be a
floating number when fractions of second are needed.
unlock
Unlock currently opened database.
Options:
--keyfile KEYFILE
Set key file used for unlocking database. It is necessary
to set a key file again when database was previously locked (see the
"lock" command).