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