Cheatsheets:Keepassxc-cli

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

keepassxc-cli is the command-line client of KeePassXC: it opens, reads and edits the same encrypted .kdbx databases as the desktop application, so an entry added from a terminal shows up in the GUI and vice versa.

New to it? keepassxc-cli help lists every command, keepassxc-cli <command> -h documents one command, and man keepassxc-cli is the full reference.

Unlocking the database

Commands that act on a database take its path as the first argument, then ask for the master password:

keepassxc-cli ls db.kdbx                            # prompts: Enter password to unlock db.kdbx
keepassxc-cli -k keyfile ls db.kdbx                 # also unlock with a key file
keepassxc-cli -k keyfile --no-password ls db.kdbx   # database protected by a key file only

The password is read from stdin: typed at the terminal (without echo), or piped by a script:

echo "$MASTER" | keepassxc-cli ls db.kdbx      # password on stdin, prompts go to stderr
echo "$MASTER" | keepassxc-cli -q ls db.kdbx   # -q: silence the prompt and secondary messages

Put global options before the command name: keepassxc-cli -q show db.kdbx site1, keepassxc-cli -k keyfile show db.kdbx site1, keepassxc-cli -y 1:7370001 show db.kdbx site1 (YubiKey slot, optional serial).

Piping the master password leaks it into the shell history and the process list. Prefer a key file, or the interactive shell below.

Interactive shell

Unlock once, then run as many commands as you like without retyping the master password:

keepassxc-cli open db.kdbx      # shell-style session, the prompt is the database name

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

export and import exist only outside the shell; close, exit and quit only inside it.

List and search

keepassxc-cli ls db.kdbx                   # root group: entries, then sub-groups
keepassxc-cli ls db.kdbx Internet          # one group
keepassxc-cli ls -R db.kdbx                # recurse into every group
keepassxc-cli ls -f -R db.kdbx             # -f: flatten, one full path per line
keepassxc-cli search db.kdbx site          # entries matching a term
keepassxc-cli search db.kdbx 'title:mail'  # field-qualified term
keepassxc-cli search db.kdbx 'has:totp'    # every entry with TOTP set up

$ keepassxc-cli ls db.kdbx
site0
Internet/
  site1
  site2
Work/
  [empty]

$ keepassxc-cli search db.kdbx site
/Internet/site1
/Work/site3

Sub-groups are printed with a trailing /, indented by two spaces per level; an empty group shows [empty]. Commands accept both Internet/site1 and /Internet/site1.

search — the same query language as 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 or !term	excludes the term
+term	the term exactly, not as a substring
a|b	either term

Show an entry

keepassxc-cli show db.kdbx site1                    # title, username, URL, notes; password reads PROTECTED
keepassxc-cli show -s db.kdbx site1                 # -s: reveal protected values too
keepassxc-cli show -a username db.kdbx site1        # value only, no field label
keepassxc-cli show -a username -a password db.kdbx Internet/site1   # several attributes, one per line
keepassxc-cli show --all db.kdbx site1              # every attribute, custom ones included
keepassxc-cli show --show-attachments db.kdbx site1 # attachment names and sizes

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

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

An entry is addressed by its title alone when that title is unique in the database, otherwise by group path and title. ls -f -R prints every valid path.

-s, -a password and --all print secrets in clear text: they stay in the terminal scrollback, and in the shell history when typed on a command line.

Copy to the clipboard

keepassxc-cli clip db.kdbx site1               # password, clipboard cleared after 10 s
keepassxc-cli clip -a username db.kdbx site1   # any attribute: username, url, notes, ...
keepassxc-cli clip db.kdbx site1 30            # clear after 30 s instead; 0 keeps it until overwritten
keepassxc-cli 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 All clipping programs failed.

TOTP

keepassxc-cli show -t db.kdbx site1                         # the current code, and nothing else
keepassxc-cli show -a username -a password -t db.kdbx site1 # ...or after the other fields
keepassxc-cli clip -t db.kdbx site1                         # copy the code to the clipboard
OTP="$(keepassxc-cli -q show -t db.kdbx site1)"             # code only, for a scripted login
keepassxc-cli show -a otp db.kdbx site1                     # the stored otpauth:// secret, to enrol another device

The code is computed locally from the secret stored in the entry: 6 digits, renewed every 30 seconds by default. No network access is needed, but a drifting system clock makes the server reject the codes.

The entry must have TOTP configured first (in the GUI: right-click the entry → TOTP → Set up TOTP…), or the command fails with Entry with path site1 has no TOTP set up.

TOTP stored beside the password is one factor, not two: whoever unlocks the database gets both. Keep TOTP codes in a separate database when the second factor has to stay independent.

Add, edit, remove

keepassxc-cli add -u user1 -g db.kdbx Internet/site3           # -g: generate the password
keepassxc-cli add -u user1 -p db.kdbx Internet/site3           # -p: prompt for the password
keepassxc-cli add -u user1 -g -L 24 -s db.kdbx Internet/site3  # generated: 24 characters, special ones included
keepassxc-cli add -u user1 -g --url https://example.com db.kdbx Internet/site3

keepassxc-cli edit -u user2 db.kdbx Internet/site3   # change one field
keepassxc-cli edit -t Mail db.kdbx Internet/site3    # rename (-t is --title here, not TOTP)
keepassxc-cli edit -g db.kdbx Internet/site3         # replace the password with a generated one
keepassxc-cli edit -p db.kdbx Internet/site3         # ...or type a new one
keepassxc-cli rm db.kdbx Internet/site3              # delete: to the recycle bin, when one is enabled

keepassxc-cli mkdir db.kdbx Internet/Sub       # new group; parent groups must exist
keepassxc-cli mv db.kdbx Internet/site3 Work   # move an entry to another group
keepassxc-cli rmdir db.kdbx Work               # remove a group

-p prompts for the entry's password, but like the master password it only reads stdin: two lines, 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

keepassxc-cli generate                          # 16 characters: lowercase, uppercase, digits
keepassxc-cli generate -L 24 -s                 # 24 characters, special ones included
keepassxc-cli generate -L 20 --exclude-similar  # avoid look-alikes such as l, 1 and I
keepassxc-cli generate -x 'a,b,c'               # exclude individual characters
keepassxc-cli generate -c 'abcdef1234'          # only from these characters
keepassxc-cli generate -e                       # add extended ASCII
keepassxc-cli generate --every-group            # at least one character from every selected group
keepassxc-cli diceware                          # 7-word passphrase
keepassxc-cli diceware -W 5                     # 5 words
keepassxc-cli diceware -w wordlist.txt          # custom word list
keepassxc-cli estimate 'some_password'          # entropy of a given password
keepassxc-cli estimate -a 'some_password'       # ...with advanced analysis

Database operations

keepassxc-cli db-create -p db.kdbx                         # new database; prompts twice for its password
keepassxc-cli db-create -p --set-key-file keyfile db.kdbx  # password and key file as two factors
keepassxc-cli db-info db.kdbx                              # entries, groups, encryption parameters
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             # drop the password factor, keep another one
keepassxc-cli export -f csv db.kdbx > export.csv           # every secret, in clear text
keepassxc-cli import export.xml new.kdbx                   # import into a new database

export writes every password in clear text — mind where the file lands, and delete it once the import is done.

Common errors

Message	Cause and fix
All clipping programs failed.	neither wl-copy nor xclip is installed: install one for clip to work
Entry with path X has no TOTP set up.	TOTP was never configured on that entry: set it up in the GUI first
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
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