A simple command line tool to interact with KeePassX databases.
KeePassX is a cross platform password management application. It is available as a GUI application for MacOSX, Linux and Windows and as an Android app (KeePassDroid), making it useful to manage passwords across multiple devices.
- View details: list groups and entries, get details for a single entry
- Add new entries and change passwords from the commandline
- Resolve conflicts: users may choose to keep their KeePassX database in a central location such as Dropbox or other synchronisation software. This results in "conflicting copies" being generated if a opens and updates the database from more than one device. kpcli avoids these conflicts, and also provides a utility to compare conflicting copies and identify where the conflicts lie.
Using pip:
pip install kpcli
From source:
git clone https://github.com/rebkwok/kpcli.git
cd kpcli
poetry install # pip install poetry first if necessary
kpcli will look for database configuration first in in environment variables, and then in a config.ini file.
The (encrypted) database password can be stored by setting STORE_ENCRYPTED_PASSWORD
to True in the config.ini file or
as an environment variable. kpcli will prompt for the password once and then every 24 hours.
NOTE:
AT YOUR OWN RISK! KEEPASSDB_PASSWORD
can be set in plaintext in the config.ini file or as an environment variable if you really want to.
If no KEEPASSDB_PASSWORD
is found, kpcli will prompt for it.
Create a config file at $(HOME)/.kp/config.ini, with at least a default profile, and your database location and credentials:
[default]
KEEPASSDB=/Users/me/mypassworddb.kdbx
If your database uses a key file, provide that location too:
[default]
KEEPASSDB=/path/to/mypassworddb.kdbx
KEYPASSDB_KEYFILE=/path/to/mykeyfile.key
More than one profile can be set for multiple databases, and switched with the -p
flag
[default]
KEEPASSDB=/path/to/db.kdbx
KEYPASSDB_KEYFILE=/path/to/mykeyfile.key
[work]
KEEPASSDB=/path/to/workdb.kdbx
By default, passwords copied to the clipboard will timeout after 5 seconds. To change the
timeout, provide a KEYPASSDB_TIMEOUT
config or environment variable.
If no config.ini file exists, kpcli will attempt to find config in the environment variables
KEEPASSDB
, KEYPASSDB_KEYFILE
and KEEPASSDB_PASSWORD
(falling back to a prompt for the password).
For more detailed usage, use --help
with any kpcli command listed below.
$ kpcli [OPTIONS] COMMAND [ARGS]...
-p, --profile TEXT
: Specify config profile to use [default: default]--loglevel TEXT
: [default: INFO]--install-completion
: Install completion for the current shell.--show-completion
: Show completion for the current shell, to copy it or customize the installation.--help
: Show this message and exit.
Group names and entry titles can be passed as partial, case-insensitive strings for matching.
ls
: List groups and entriesadd-group
: Add a new grouprm-group
: delete a groupget
: Fetch details for a single entrycp
: Copy entry attribute to clipboardadd
: Add a new entryedit
: Edit an entry's attributes (except password)change-password
: Change entry passwordrm
: Delete an entrycompare
: Compare potentially conflicting copies of a KeePassX Database and report conflicts
$ kpcli ls
Database: /path/to/db.kdbx
================================================================================
Groups
================================================================================
Root
Internet
Communications
...
$ kpcli ls --group comm --entries
Database: /path/to/db.kdbx
================================================================================
Communications
================================================================================
my email
work email
...
$ kpcli --profile work ls
Database: /path/to/workdb.kdbx
================================================================================
Groups
================================================================================
Root
Work
...
By group and entry title, separated with /. Note partial matches are allowed.
If multiple matching entries are found, all will be listed.
$ kpcli get comm/email
Database: /path/to/db.kdbx
================================================================================
Communications/my email
================================================================================
name: Communications/my email
username: [email protected]
password: **********
URL:
Notes: This is my main email address
If multiple entries match, kpcli prompts for a selection.
Password copy times out after 5 seconds by default (change by setting KEEPASS_TIMEOUT
in config.ini
)
$ kpcli cp comm/email
Entry: Communications/my email
Password copied to clipboard; timeout in 5 seconds
Press any key to clear clipboard and exit:
$ kpcli cp comm/email username
Entry: Communications/my email
username copied to clipboard
Copies first the username, waits for a keypress, then password.
$ kpcli cp comm/email both
Entry: Communications/my email
Username '[email protected]' copied to clipboard
Press any key to copy password: c
Password copied to clipboard; timeout in 5 seconds
Press any key to clear clipboard and exit:
$ kpcli add
kpcli will prompt for required fields.
$ kpcli change-password comm/email
kpcli will prompt for new password.
In the example below, kpcli found one conflicting db to compare.
The entry with title "entry1" in group "blue" is present in the conflicting db, but missing
in the main db.
Entry blue/entry2 is present in the main db but missing in the conflicting db.
Entry red/entry3 is present in both dbs, but has conflicting username and password values.
$ kpcli compare
Database: path/to/db.kdbx
Database password:
Looking for conflicting files...
================================================================================
Comparison db: path/to/db_conflicting_copy.kdbx
================================================================================
╔════════════╤═════════════╤════════════════════╗
║ Main │ Conflicting │ Conflicting fields ║
╠════════════╪═════════════╪════════════════════╣
║ - │ blue/entry1 │ ║
╟────────────┼─────────────┼────────────────────╢
║ blue/entry2│ - │ ║
╟────────────┼─────────────┼────────────────────╢
║ red/entry3 │ red/entry3 │ username, password ║
╚════════════╧═════════════╧════════════════════╝