Cheatsheets:Keepassxc-cli: Difference between revisions

From Wikibase
Jump to navigation Jump to search
← Older edit

Rongzhou (talk | contribs)

4 user groups
2,877 edits
Fix REPL prompt in syntaxhighlight blocks: use a raw > (the highlighter escapes HTML entities, so > printed literally). AI-assisted (RonzzWikiCowriter) (via update-page on MediaWiki MCP Server)
 
(2 intermediate revisions by 2 users not shown)
Line 9: Line 9:
* <code>man keepassxc-cli</code> provides a full reference
* <code>man keepassxc-cli</code> provides a full reference


== DB ops ==
== DB ops: <code>db-create, db-info, db-edit, import, export</code> ==


KeePassXC stores all your secrets in encrypted <code>.kdbx</code> files.
KeePassXC stores all your secrets in encrypted <code>.kdbx</code> files.
Line 31: Line 31:
</blockquote>
</blockquote>


== Keepassxc-cli repl ==
== <code>open</code> DB ==


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


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
keepassxc-cli open Passwords.kdbx            # enter a repl on Passwords.kdbx; the prompt is the database name
keepassxc-cli open Passwords.kdbx            # will prompt for master password
keepassxc-cli -k keyfile open Passwords.kdbx  # ...if a key file is also required
keepassxc-cli -k keyfile open Passwords.kdbx  # ...if a key file is also required
</syntaxhighlight>
</syntaxhighlight>
This activates a command repl, eliminating the need to retype the master password for each command:


<pre>
<pre>
Line 51: Line 53:
<code>export</code> and <code>import</code> do not work in the repl.
<code>export</code> and <code>import</code> do not work in the repl.


Every other command works in both forms: <code>Passwords&gt; ls</code> inside the repl, <code>keepassxc-cli ls Passwords.kdbx</code> outside it, the database being then the first argument. The sections below use the repl form.
Every other command works in both forms:
 
* <code>Passwords&gt; [command]</code> inside the repl
* <code>keepassxc-cli [command] xxx.kdbx</code> as standalone CLI command
</blockquote>
</blockquote>


== Edit secrets ==
== Generate passwords/passphrases ==


'''add''' creates an entry, '''edit''' changes one, '''rm''' deletes it, and '''mkdir''', '''mv''' and '''rmdir''' organise the groups:
=== <code>generate</code> (passwords) ===


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
Passwords> add -u user1 -g Internet/site3          # -g: generate the password
Passwords> generate                          # 16 characters: lowercase, uppercase, digits
Passwords> add -u user1 -p Internet/site3          # -p: prompt for the password
Passwords> generate -L 24                    # increase length to 24
Passwords> add -u user1 -g -L 24 -s Internet/site3  # generated: 24 characters, special ones included
Passwords> generate --special                # enable special characters
Passwords> add -u user1 -g --url https://example.com Internet/site3
Passwords> generate --exclude-similar        # avoid look-alikes such as l, 1 and I
Passwords> edit -u user2 Internet/site3            # change one field
Passwords> generate -x 'a,b,c'              # exclude individual characters
Passwords> edit -t Mail Internet/site3            # rename the entry
Passwords> generate -c 'abcdef1234'          # only from these characters
Passwords> edit -g Internet/site3                  # replace the password with a generated one
Passwords> generate --every-group            # at least one number, one uppercase letter, one lowercase letter, and a special character if enabled
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
</syntaxhighlight>
</syntaxhighlight>


<code>add</code> and <code>edit</code> take the same options, except <code>-t</code>:
=== <code>estimate</code> (password entropy) ===


{| class="wikitable"
<syntaxhighlight lang="bash" copy>
! Option !! Effect
Passwords> estimate 'some_password'    # entropy of a given password
|-
Passwords> estimate -a 'some_password' # -a: advanced analysis
| <code>-u NAME</code>, <code>--username</code> || set the username
</syntaxhighlight>
|-
| <code>--url URL</code> || set the URL
|-
| <code>--notes TEXT</code> || set the notes; <code>\n</code> becomes a line break
|-
| <code>-p</code>, <code>--password-prompt</code> || ask for the entry's password
|-
| <code>-g</code>, <code>--generate</code> || generate the entry's password (see [[#Generate passwords|the generator options]])
|-
| <code>-t TITLE</code>, <code>--title</code> || rename the entry — <code>edit</code> only
|}


<blockquote>
=== <code>diceware</code> (passphrases) ===
<code>edit</code> refuses to run without at least one field option: <code>Not changing any field for entry Internet/site3.</code>
</blockquote>
 
<blockquote>
<code>-p</code> reads the entry's password from <code>stdin</code>, 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:


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
printf 'masterpass\nnewpass\n' | keepassxc-cli -q add -p -u user1 db.kdbx Internet/site3
Passwords> diceware                  # default length: 7 words
Passwords> diceware -W 5            # 5 words
Passwords> diceware -w wordlist.txt  # use custom word list
</syntaxhighlight>
</syntaxhighlight>
</blockquote>


== Generate passwords ==
== <code>add, edit, rm, mv</code> entries and <code>mkdir, rmdir</code> ==


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
Passwords> generate                         # 16 characters: lowercase, uppercase, digits
Passwords> mkdir Internet                         # make a new group
Passwords> generate -L 24 -s                 # 24 characters, special ones included
Passwords> mkdir Internet/Sub                      # make a new subgroup: parent groups must exist
Passwords> generate -L 20 --exclude-similar  # avoid look-alikes such as l, 1 and I
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> generate -x 'a,b,c'              # exclude individual characters
Passwords> add -u user1 -g -L 24 -s Internet/site3 # -g: instead of prompting for password, generate one: legnth 24, special chars included
Passwords> generate -c 'abcdef1234'          # only from these characters
Passwords> add -u user1 -g --url https://example.com Internet/site3 # --url: for internet sites, consider specifying the login url for record
Passwords> generate --every-group           # at least one character from every selected group
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
</syntaxhighlight>
</syntaxhighlight>


The same options apply to <code>generate</code>, to <code>add -g</code> and to <code>edit -g</code>:
<blockquote>
Group = folder. Use groups to organise entries.
</blockquote>


{| class="wikitable"
<blockquote>
! Option !! Effect
<code>-g</code> can be coupled with the same options as the <code>generate</code> command.
|-
</blockquote>
| <code>-L N</code>, <code>--length</code> || length of the password, 16 by default
|-
| <code>-l</code>, <code>--lower</code> || lowercase letters (enabled by default)
|-
| <code>-U</code>, <code>--upper</code> || uppercase letters (enabled by default)
|-
| <code>-n</code>, <code>--numeric</code> || digits (enabled by default)
|-
| <code>-s</code>, <code>--special</code> || special characters (disabled by default)
|-
| <code>-e</code>, <code>--extended</code> || extended ASCII characters (disabled by default)
|-
| <code>-x CHARS</code>, <code>--exclude</code> || exclude these characters, comma-separated
|-
| <code>-c CHARS</code>, <code>--custom</code> || draw from these characters only
|-
| <code>--exclude-similar</code> || drop look-alikes such as <code>l</code>, <code>1</code> and <code>I</code>
|-
| <code>--every-group</code> || at least one character from every selected class
|}


'''diceware''' — passphrases:
<blockquote>
 
<code>add</code> and <code>edit</code> take similar options.
<syntaxhighlight lang="bash" copy>
</blockquote>
Passwords> diceware                  # 7 words
Passwords> diceware -W 5            # 5 words
Passwords> diceware -w wordlist.txt  # custom word list
</syntaxhighlight>


{| class="wikitable"
{| class="wikitable"
! Option !! Effect
! Additional option !! Effect
|-
|-
| <code>-W N</code>, <code>--words</code> || number of words, 7 by default
| <code>--notes TEXT</code> || attach notes to an entry; <code>\n</code> becomes a line break
|-
| <code>-w FILE</code>, <code>--word-list</code> || custom word list: more than 1000 words are required, and a warning is printed below 4000
|}
|}


'''estimate''' — entropy of a password:
== <code>ls</code> ==
 
<syntaxhighlight lang="bash" copy>
Passwords> estimate 'some_password'    # entropy of a given password
Passwords> estimate -a 'some_password'  # -a: advanced analysis
</syntaxhighlight>
 
== List ==


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
Line 171: Line 131:
</syntaxhighlight>
</syntaxhighlight>


{| class="wikitable"
== <code>search</code> ==
! Option !! Effect
|-
| <code>-R</code>, <code>--recursive</code> || list the contents of the sub-groups too
|-
| <code>-f</code>, <code>--flatten</code> || print <code>group-path/title</code> on one line per entry, instead of an indented tree
|}
 
== Search ==


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
Line 205: Line 157:
|}
|}


== Show an entry ==
== <code>show</code> entries ==


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
Passwords> show site1                                    # default fields; the password reads PROTECTED
Passwords> show site1                                    # show default fields
Passwords> show -s Internet/site1                        # -s: reveal protected values too
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
Passwords> show -a username -a password Internet/site1  # specific attributes, one per line. use --all for all
</syntaxhighlight>
</syntaxhighlight>


{| class="wikitable"
{| class="wikitable"
! Option !! Effect
! Additional option !! Effect
|-
| <code>-a ATTR</code>, <code>--attributes</code> || print the named attribute, without its field label; repeat the flag for several, printed one per line
|-
| <code>-s</code>, <code>--show-protected</code> || reveal protected values in clear text
|-
| <code>--all</code> || every attribute, custom ones included
|-
|-
| <code>--show-attachments</code> || attachment names and sizes
| <code>--show-attachments</code> || attachment names and sizes
|-
| <code>-t</code>, <code>--totp</code> || the current TOTP code (see [[#TOTP]])
|}
|}
Naming the attribute is what makes the output script-friendly:
<syntaxhighlight lang="bash" copy>
PASSWORD="$(keepassxc-cli -q show -a password Passwords.kdbx Internet/site1)"
</syntaxhighlight>


<blockquote>
<blockquote>
Line 239: Line 177:
</blockquote>
</blockquote>


== Clip: Copy to the clipboard ==
== <code>clip</code> to the clipboard ==


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


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
Passwords> clip site1              # copy the password; the clipboard is cleared after 10 s
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 -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
</syntaxhighlight>
</syntaxhighlight>


Line 255: Line 190:
</blockquote>
</blockquote>


== TOTP ==
== TOTP (<code>-t</code>) ==


<blockquote>
<blockquote>
'''Caveat''': <code>keepassxc-cli</code> currently only supports generating a TOTP from an entry already set up. The setup must be done in the GUI.
'''Caveat''': Currently, TOTP setup is a GUI-only feature in KeePassXC. <code>keepassxc-cli</code> 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 <code>oathtool --totp --base32 [SECRET_KEY]</code> to generate TOTP.
</blockquote>
</blockquote>


<syntaxhighlight lang="bash" copy>
<syntaxhighlight lang="bash" copy>
Passwords> show -t site1                            # show the current code
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> clip -t site1                            # copy the code to the clipboard
Passwords> show -a otp site1                        # the stored otpauth:// secret, to enrol another device
Passwords> show -a otp site1                        # show the stored oath secret, to enrol another device, etc.
OTP="$(keepassxc-cli -q show -t Passwords.kdbx site1)"  # code only, outside the repl, for a scripted login
</syntaxhighlight>
</syntaxhighlight>


Line 283: Line 216:
|-
|-
| <code>Attribute "X" not found.</code> || wrong attribute name: list them with <code>show --all</code>
| <code>Attribute "X" not found.</code> || wrong attribute name: list them with <code>show --all</code>
|-
| <code>Not changing any field for entry X.</code> || <code>edit</code> was given no field option: pass at least one, e.g. <code>edit -u user2 Internet/site3</code>
|-
| the command waits for input in a script || the master password is read from <code>stdin</code>: pipe it, or unlock with <code>-k keyfile</code>
|}
|}


Line 292: Line 221:


* [https://keepassxc.org/docs/KeePassXC_UserGuide.html KeePassXC user guide] — the official guide: TOTP setup, search syntax, browser and SSH agent integration
* [https://keepassxc.org/docs/KeePassXC_UserGuide.html KeePassXC user guide] — the official guide: TOTP setup, search syntax, browser and SSH agent integration
* [https://github.com/keepassxreboot/keepassxc/blob/develop/docs/man/keepassxc-cli.1.adoc keepassxc-cli(1) man page] — every command and every option
* <code>keepassxc-cli help</code> and <code>man keepassxc-cli</code> — the same reference, offline
* <code>analyze</code> — offline Have I Been Pwned check against a downloaded password-hash list
* <code>merge</code> — merge two databases into one
* <code>attachment-import</code>, <code>attachment-export</code>, <code>attachment-rm</code> — manage file attachments
* [[Cheatsheets:LinuxCLI/ssh]] — SSH keys and <code>ssh-agent</code>, which KeePassXC can feed


[[Category:LinuxCLI]]
[[Category:LinuxCLI]]

Latest revision as of 18:40, 30 September 2026

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

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
Retrieved from "https://wikibase.ronzz.org/index.php?title=Cheatsheets:Keepassxc-cli&oldid=8482"