kpsh(1) General Commands Manual kpsh(1)

kpsh - command line password manager

kpsh [OPTIONS] [DATABASE]

kpsh [--command <COMMAND>...] [OPTIONS] [DATABASE]

command | kpsh [OPTIONS] [DATABASE]

kpsh --daemon [OPTIONS] [DATABASE]

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:

•X11: xclip
•Wayland: wl-copy

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).

kpsh will try to unlock database on its first use when it is started with a --password or --password-command options.

Passwords passed by the --password option are insecure. They may be seen on a process list and in the shell's command history. If you can, you should avoid this option and pass a command to --password-command which securely accesses the database password.

One way to securely store and retrieve a master password is to encrypt it with a gpg and configure gpg-agent to either automatically unlock during user login a private key used for encryption, or to prompt for a password. The latter usually results in showing a graphical pinentry window.

$ echo -n 'some password' | gpg --encrypt --recipient <KEY ID> --output pass.gpg
$ kpsh --password-command 'gpg --quiet --decrypt pass.gpg'

You may use system keyring (for example a gnome-keyring-daemon) to store and retrieve a master password. Most systems automatically configure keyrings to unlock during a user login, so this should effectively allow a "passwordless" database access.

$ secret-tool store --label="KeePass passwords.kdbx" keepass passwords.kdbx
Password: (prompt)
$ kpsh --password-command 'secret-tool lookup keepass passwords.kdbx'

You may use databases which require only a presence of Key File. kpsh accepts it via a --keyfile option.

kpsh-client(1), kpsh-menu(1)

Michał Góral <dev@goral.net.pl>

Source code: https://git.goral.net.pl/keepass-shell.git

2024-12-21