Cheatsheets:Keepassxc-cli

Languages: English · français · Esperanto

Quick reference for smart people — part of our Linux cheatsheets collection.

keepassxc-cli is the command-line client of KeePassXC: it can open, read and edit the same encrypted .kdbx databases as the desktop application, to manage your secrets from a terminal.

New to it?

keepassxc-cli help lists every command
keepassxc-cli <command> -h documents one command
man keepassxc-cli provides a full reference

DB ops

KeePassXC stores all your secrets in encrypted .kdbx files.

keepassxc-cli db-create -p db.kdbx                         # create a new database
keepassxc-cli db-create --set-key-file keyfile db.kdbx     # create a new database protected by a key file
keepassxc-cli db-info db.kdbx                              # show info on a .kdbx DB
keepassxc-cli db-edit -p db.kdbx                           # change the master password
keepassxc-cli db-edit --set-key-file keyfile db.kdbx       # add or replace the key file
keepassxc-cli db-edit --unset-password db.kdbx             # remove the password encryption
keepassxc-cli export -f csv db.kdbx > export.csv           # export every secret to csv in clear text
keepassxc-cli export -f xml db.kdbx > export.xml           # export every secret to xml to be reimported into another .kdbx
keepassxc-cli import export.xml new.kdbx                   # import from a previously exported .xml into a new database

Any file created by export should be considered extremely sensitive, as it contains all your secrets in clear text.
import currently only accepts a .xml file previously exported by KeePassXC.

Keepassxc-cli repl

Once the .kdbx is set up, the first step to interact with it is almost always to enter the command repl on a particular .kdbx database, otherwise you have to retype the master password for every single command.

keepassxc-cli open Passwords.kdbx             # enter a repl on Passwords.kdbx; the prompt is the database name
keepassxc-cli -k keyfile open Passwords.kdbx  # ...if a key file is also required

Passwords> ls
Passwords> show -s Internet/site1
Passwords> clip -t Internet/site1
Passwords> close                   # close the current database, stay in the repl
Passwords> exit                    # exit the repl

export and import do not work in the repl.
Every other command works in both forms: Passwords> ls inside the repl, keepassxc-cli ls Passwords.kdbx outside it, the database being then the first argument. The sections below use the repl form.

Edit secrets

add creates an entry, edit changes one, rm deletes it, and mkdir, mv and rmdir organise the groups:

Passwords> add -u user1 -g Internet/site3           # -g: generate the password
Passwords> add -u user1 -p Internet/site3           # -p: prompt for the password
Passwords> add -u user1 -g -L 24 -s Internet/site3  # generated: 24 characters, special ones included
Passwords> add -u user1 -g --url https://example.com Internet/site3
Passwords> edit -u user2 Internet/site3            # change one field
Passwords> edit -t Mail Internet/site3             # rename the entry
Passwords> edit -g Internet/site3                  # replace the password with a generated one
Passwords> rm Internet/site3                       # delete: to the recycle bin, when one is enabled
Passwords> mkdir Internet/Sub                      # new group; parent groups must exist
Passwords> mv Internet/site3 Work                  # move an entry to another group
Passwords> rmdir Work                              # remove a group

add and edit take the same options, except -t:

Option	Effect
`-u NAME`, `--username`	set the username
`--url URL`	set the URL
`--notes TEXT`	set the notes; `\n` becomes a line break
`-p`, `--password-prompt`	ask for the entry's password
`-g`, `--generate`	generate the entry's password (see the generator options)
`-t TITLE`, `--title`	rename the entry — `edit` only

edit refuses to run without at least one field option: Not changing any field for entry Internet/site3.

-p reads the entry's password from stdin, like the master password does. As a one-off command outside the repl, the two lines come in order — master password, then the entry's:
printf 'masterpass\nnewpass\n' | keepassxc-cli -q add -p -u user1 db.kdbx Internet/site3

Generate passwords

Passwords> generate                          # 16 characters: lowercase, uppercase, digits
Passwords> generate -L 24 -s                 # 24 characters, special ones included
Passwords> generate -L 20 --exclude-similar  # avoid look-alikes such as l, 1 and I
Passwords> generate -x 'a,b,c'               # exclude individual characters
Passwords> generate -c 'abcdef1234'          # only from these characters
Passwords> generate --every-group            # at least one character from every selected group

The same options apply to generate, to add -g and to edit -g:

Option	Effect
`-L N`, `--length`	length of the password, 16 by default
`-l`, `--lower`	lowercase letters (enabled by default)
`-U`, `--upper`	uppercase letters (enabled by default)
`-n`, `--numeric`	digits (enabled by default)
`-s`, `--special`	special characters (disabled by default)
`-e`, `--extended`	extended ASCII characters (disabled by default)
`-x CHARS`, `--exclude`	exclude these characters, comma-separated
`-c CHARS`, `--custom`	draw from these characters only
`--exclude-similar`	drop look-alikes such as `l`, `1` and `I`
`--every-group`	at least one character from every selected class

diceware — passphrases:

Passwords> diceware                  # 7 words
Passwords> diceware -W 5             # 5 words
Passwords> diceware -w wordlist.txt  # custom word list

Option	Effect
`-W N`, `--words`	number of words, 7 by default
`-w FILE`, `--word-list`	custom word list: more than 1000 words are required, and a warning is printed below 4000

estimate — entropy of a password:

Passwords> estimate 'some_password'     # entropy of a given password
Passwords> estimate -a 'some_password'  # -a: advanced analysis

List

Passwords> ls            # root group: entries, then sub-groups
Passwords> ls Internet   # one group
Passwords> ls -R         # recurse into every group
Passwords> ls -f -R      # one full path per line

Option	Effect
`-R`, `--recursive`	list the contents of the sub-groups too
`-f`, `--flatten`	print `group-path/title` on one line per entry, instead of an indented tree

Search

Passwords> search site          # entries matching a term
Passwords> search 'title:mail'  # field-qualified term
Passwords> search 'has:totp'    # every entry with TOTP set up

search — the same query language as in the GUI search box:

Syntax	Matches
`title:`, `username:`, `url:`, `notes:`, `group:`, `tag:`	one field only; abbreviated forms work (`t:`, `u:`, `g:`, ...)
`has:totp`	entries with TOTP configured
`is:weak`, `is:expired`	weak or expired passwords
`!term`	excludes the term
`+term`	exact term only, not as a substring
`a\|b`	either term

Show an entry

Passwords> show site1                                    # default fields; the password reads PROTECTED
Passwords> show -s Internet/site1                        # -s: reveal protected values too
Passwords> show -a username -a password Internet/site1   # specific attributes, one per line

Option	Effect
`-a ATTR`, `--attributes`	print the named attribute, without its field label; repeat the flag for several, printed one per line
`-s`, `--show-protected`	reveal protected values in clear text
`--all`	every attribute, custom ones included
`--show-attachments`	attachment names and sizes
`-t`, `--totp`	the current TOTP code, see TOTP

Naming the attribute is what makes the output script-friendly:

PASSWORD="$(keepassxc-cli -q show -a password Passwords.kdbx Internet/site1)"

An entry can be addressed by title alone when that title is unique, otherwise it must be addressed by group-path/title.
ls -f -R prints every valid path.

Clip: Copy to the clipboard

Replace show with clip to copy to the clipboard instead of printing to stdout.

Passwords> clip site1              # copy the password; the clipboard is cleared after 10 s
Passwords> clip -a username site1  # copy any attribute of the entry: username, url, notes, ...
Passwords> clip -t site1           # copy the current TOTP code to the clipboard
Passwords> clip site1 30           # clear after 30 s instead; 0 keeps it until it is overwritten
Passwords> clip -b github          # unique title match only, no group path needed

On Linux, clip pipes to wl-copy (Wayland) or xclip (X11); without either one it fails with error All clipping programs failed.

TOTP

Caveat: keepassxc-cli currently only supports generating a TOTP from an entry already set up. The setup must be done in the GUI.

Passwords> show -t site1                             # show the current code
Passwords> show -a password -t Internet/site1        # ...alongside other fields
Passwords> clip -t site1                             # copy the code to the clipboard
Passwords> show -a otp site1                         # the stored otpauth:// secret, to enrol another device
OTP="$(keepassxc-cli -q show -t Passwords.kdbx site1)"  # code only, outside the repl, for a scripted login

The code is computed locally from the secret stored in the entry and the local system clock time. A drifting system clock would generate invalid codes.

Common errors

Message	Cause and fix
`All clipping programs failed.`	neither `wl-copy` nor `xclip` is installed: install one for `clip` to work
`Could not find entry with path X.`	the title is not unique, or the group path is wrong: list the paths with `ls -f -R`
`Attribute "X" not found.`	wrong attribute name: list them with `show --all`
`Not changing any field for entry X.`	`edit` was given no field option: pass at least one, e.g. `edit -u user2 Internet/site3`
the command waits for input in a script	the master password is read from `stdin`: pipe it, or unlock with `-k keyfile`

For more

KeePassXC user guide — the official guide: TOTP setup, search syntax, browser and SSH agent integration
keepassxc-cli(1) man page — every command and every option
keepassxc-cli help and man keepassxc-cli — the same reference, offline
analyze — offline Have I Been Pwned check against a downloaded password-hash list
merge — merge two databases into one
attachment-import, attachment-export, attachment-rm — manage file attachments
Cheatsheets:LinuxCLI/ssh — SSH keys and ssh-agent, which KeePassXC can feed