Cheatsheets:Keepassxc-cli

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 just like the desktop application to manage your secrets

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 store 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 keepassxc-cli repl on Passwords.kdbx shell-style session, 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                    # exist repl

export and import do not work in repl

Edit secrets

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

List

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

Search

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

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

keepassxc-cli show db.kdbx site1                    # -s: reveal protected values too
keepassxc-cli show -a username -a password db.kdbx Internet/site1   # show specific 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 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 clipboard instead of printing to stout.

keepassxc-cli clip db.kdbx site1               # copy password of the entry to the clipboard. clipboard will be cleared after 10 s
keepassxc-cli clip -a username db.kdbx site1   # copy any attribute of the entry: username, url, notes, ...
keepassxc-cli clip -t db.kdbx site1            # copy current totp code to system clipboard

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 TOTP from an entry already setup. The setup must be done in GUI.

keepassxc-cli show -t db.kdbx site1                         # show the current code
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 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

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