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: db-create, db-info, db-edit, import, export

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.

open DB

Once the encrypted .kdbx is set up, open to interact with it.

keepassxc-cli open Passwords.kdbx             # will prompt for master password
keepassxc-cli -k keyfile open Passwords.kdbx  # ...if a key file is also required

This activates a command repl, eliminating the need to retype the master password for each command:

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> [command] inside the repl
• keepassxc-cli [command] xxx.kdbx as standalone CLI command

Generate passwords/passphrases

generate (passwords)

Passwords> generate                          # 16 characters: lowercase, uppercase, digits
Passwords> generate -L 24                    # increase length to 24
Passwords> generate --special                # enable special characters
Passwords> generate --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 number, one uppercase letter, one lowercase letter, and a special character if enabled

estimate (password entropy)

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

diceware (passphrases)

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

add, edit, rm, mv entries and mkdir, rmdir

Passwords> mkdir Internet                          # make a new group
Passwords> mkdir Internet/Sub                      # make a new subgroup: parent groups must exist
Passwords> add -u user1 -p Internet/site3          # create a new entry with username (-u) user1, at path Internet/site3, and prompt for password (-p)
Passwords> add -u user1 -g -L 24 -s Internet/site3 # -g: instead of prompting for password, generate one: legnth 24, special chars included
Passwords> add -u user1 -g --url https://example.com Internet/site3 # --url: for internet sites, consider specifying the login url for record
Passwords> edit -u newUser Internet/site3            # update username (-u) of entry Internet/site3 to newUser
Passwords> edit -t Mail Internet/site3             # rename the entry Internet/site3 to Mail
Passwords> edit -g Internet/site3                  # generated a new password for entry Internet/site3
Passwords> mv Internet/site3 Work                  # move an entry to another group
Passwords> rm Internet/site3                       # delete entry
Passwords> rmdir Work                              # remove a group

Group = folder. Use groups to organise entries.

-g can be coupled with the same options as the generate command.

add and edit take similar options.

Additional option	Effect
--notes TEXT	attach notes to an entry; \n becomes a line break

ls

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

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 entries

Passwords> show site1                                    # show default fields
Passwords> show -s Internet/site1                        # -s: reveal protected fields such as password
Passwords> show -a username -a password Internet/site1   # specific attributes, one per line. use --all for all

Additional option	Effect
--show-attachments	attachment names and sizes

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 to the clipboard

Replace show with clip to copy to the clipboard instead of printing to stdout. In general, the same options stay available

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

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

TOTP (-t)

Caveat: Currently, TOTP setup is a GUI-only feature in KeePassXC. keepassxc-cli only supports generating a TOTP from an entry already set up. A workaround to stay in the CLI is to store the oath secret key as password, then use an external TOTP generator such as oathtool --totp --base32 [SECRET_KEY] to generate TOTP.

Passwords> show -t site1                             # show the current code
Passwords> clip -t site1                             # copy the code to the clipboard
Passwords> show -a otp site1                         # show the stored oath secret, to enrol another device, etc.

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