Cheatsheets:Keepassxc-cli - Revision history

Rongzhou: Rongzhou moved page Cheatsheets:LinuxCLI/Password management to Cheatsheets:Keepassxc-cli

2026-09-30T18:40:30Z

Rongzhou moved page Cheatsheets:LinuxCLI/Password management to Cheatsheets:Keepassxc-cli

← Older revision		Revision as of 18:40, 30 September 2026
(No difference)

Rongzhou at 18:39, 30 September 2026

2026-09-30T18:39:18Z

Show changes

RonzzWikiCowriterAI: Show table: label the section link as TOTP instead of the raw #TOTP anchor. AI-assisted (RonzzWikiCowriter) (via update-page on MediaWiki MCP Server)

2026-09-30T09:54:54Z

Show table: label the section link as TOTP instead of the raw #TOTP anchor. AI-assisted (RonzzWikiCowriter) (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:54, 30 September 2026
Line 224:		Line 224:
	\| <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]])		\| <code>-t</code>, <code>--totp</code> \|\| the current TOTP code, see [[#TOTP\|TOTP]]
	\|}		\|}

RonzzWikiCowriterAI: 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)

2026-09-30T09:54:43Z

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)

RonzzWikiCowriterAI: Rewrite the command sections in REPL form, add option tables for add/edit, generate, ls, show; fix the Search lead-in that rendered as preformatted text and a few typos. Implemented the HTML-comment advice (comments now removed). AI-assisted (RonzzWikiCowriter) (via update-page on MediaWiki MCP Server)

2026-09-30T09:54:18Z

Rewrite the command sections in REPL form, add option tables for add/edit, generate, ls, show; fix the Search lead-in that rendered as preformatted text and a few typos. Implemented the HTML-comment advice (comments now removed). AI-assisted (RonzzWikiCowriter) (via update-page on MediaWiki MCP Server)

Show changes

Rongzhou at 09:52, 30 September 2026

2026-09-30T09:52:20Z

Show changes

RonzzWikiCowriterAI: New cheatsheet: basic keepassxc-cli operations, including TOTP. AI-assisted (RonzzWikiCowriter) (via create-page on MediaWiki MCP Server)

2026-09-30T08:37:10Z

New cheatsheet: basic keepassxc-cli operations, including TOTP. AI-assisted (RonzzWikiCowriter) (via create-page on MediaWiki MCP Server)

New page

{{DesktopLinux}}

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

New to it? <code>keepassxc-cli help</code> lists every command, <code>keepassxc-cli <command> -h</code> documents one command, and <code>man keepassxc-cli</code> 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:

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

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

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

<blockquote>
'''Put global options before the command name:''' <syntaxhighlight lang="bash" inline>keepassxc-cli -q show db.kdbx site1</syntaxhighlight>, <syntaxhighlight lang="bash" inline>keepassxc-cli -k keyfile show db.kdbx site1</syntaxhighlight>, <syntaxhighlight lang="bash" inline>keepassxc-cli -y 1:7370001 show db.kdbx site1</syntaxhighlight> (YubiKey slot, optional serial).
</blockquote>

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

== Interactive shell ==

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

<syntaxhighlight lang="bash" copy>
keepassxc-cli open db.kdbx # shell-style session, the prompt is the database name
</syntaxhighlight>

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

<blockquote>
<code>export</code> and <code>import</code> exist only outside the shell; <code>close</code>, <code>exit</code> and <code>quit</code> only inside it.
</blockquote>

== List and search ==

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

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

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

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

'''search''' — the same query language as the GUI search box:

{| class="wikitable"
! Syntax !! Matches
|-
| <code>title:</code>, <code>username:</code>, <code>url:</code>, <code>notes:</code>, <code>group:</code>, <code>tag:</code> || one field only; abbreviated forms work (<code>t:</code>, <code>u:</code>, <code>g:</code>, ...)
|-
| <code>has:totp</code> || entries with TOTP configured
|-
| <code>is:weak</code>, <code>is:expired</code> || weak or expired passwords
|-
| <code>-term</code> or <code>!term</code> || excludes the term
|-
| <code>+term</code> || the term exactly, not as a substring
|-
| <code>a|b</code> || either term
|}

== Show an entry ==

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

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

<syntaxhighlight lang="bash" copy>
PASSWORD="$(keepassxc-cli -q show -a password db.kdbx Internet/site1)"
</syntaxhighlight>

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

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

== Copy to the clipboard ==

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

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

== TOTP ==

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

<blockquote>
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.
</blockquote>

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

<blockquote>
'''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.
</blockquote>

== Add, edit, remove ==

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

<blockquote>
<code>-p</code> prompts for the entry's password, but like the master password it only reads <code>stdin</code>: two lines, in order — master password, then the entry's:
<syntaxhighlight lang="bash" copy>
printf 'masterpass\nnewpass\n' | keepassxc-cli -q add -p -u user1 db.kdbx Internet/site3
</syntaxhighlight>
</blockquote>

== Generate passwords ==

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

== Database operations ==

<syntaxhighlight lang="bash" copy>
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
</syntaxhighlight>

<blockquote>
'''<code>export</code> writes every password in clear text''' — mind where the file lands, and delete it once the import is done.
</blockquote>

== Common errors ==

{| class="wikitable"
! Message !! Cause and fix
|-
| <code>All clipping programs failed.</code> || neither <code>wl-copy</code> nor <code>xclip</code> is installed: install one for <code>clip</code> to work
|-
| <code>Entry with path X has no TOTP set up.</code> || TOTP was never configured on that entry: set it up in the GUI first
|-
| <code>Could not find entry with path X.</code> || the title is not unique, or the group path is wrong: list the paths with <code>ls -f -R</code>
|-
| <code>Attribute "X" not found.</code> || wrong attribute name: list them with <code>show --all</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>
|}

== For more ==

* [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]]

← Older revision		Revision as of 09:54, 30 September 2026
Line 59:		Line 59:

	<syntaxhighlight lang="bash" copy>		<syntaxhighlight lang="bash" copy>
	Passwords~~>~~ add -u user1 -g Internet/site3 # -g: generate the password		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 -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 -L 24 -s Internet/site3 # generated: 24 characters, special ones included
	Passwords~~>~~ add -u user1 -g --url https://example.com Internet/site3		Passwords> add -u user1 -g --url https://example.com Internet/site3
	Passwords~~>~~ edit -u user2 Internet/site3 # change one field		Passwords> edit -u user2 Internet/site3 # change one field
	Passwords~~>~~ edit -t Mail Internet/site3 # rename the entry		Passwords> edit -t Mail Internet/site3 # rename the entry
	Passwords~~>~~ edit -g Internet/site3 # replace the password with a generated one		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> rm Internet/site3 # delete: to the recycle bin, when one is enabled
	Passwords~~>~~ mkdir Internet/Sub # new group; parent groups must exist		Passwords> mkdir Internet/Sub # new group; parent groups must exist
	Passwords~~>~~ mv Internet/site3 Work # move an entry to another group		Passwords> mv Internet/site3 Work # move an entry to another group
	Passwords~~>~~ rmdir Work # remove a group		Passwords> rmdir Work # remove a group
	</syntaxhighlight>		</syntaxhighlight>

Line 105:		Line 105:

	<syntaxhighlight lang="bash" copy>		<syntaxhighlight lang="bash" copy>
	Passwords~~>~~ generate # 16 characters: lowercase, uppercase, digits		Passwords> generate # 16 characters: lowercase, uppercase, digits
	Passwords~~>~~ generate -L 24 -s # 24 characters, special ones included		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 -L 20 --exclude-similar # avoid look-alikes such as l, 1 and I
	Passwords~~>~~ generate -x 'a,b,c' # exclude individual characters		Passwords> generate -x 'a,b,c' # exclude individual characters
	Passwords~~>~~ generate -c 'abcdef1234' # only from these characters		Passwords> generate -c 'abcdef1234' # only from these characters
	Passwords~~>~~ generate --every-group # at least one character from every selected group		Passwords> generate --every-group # at least one character from every selected group
	</syntaxhighlight>		</syntaxhighlight>

Line 142:		Line 142:

	<syntaxhighlight lang="bash" copy>		<syntaxhighlight lang="bash" copy>
	Passwords~~>~~ diceware # 7 words		Passwords> diceware # 7 words
	Passwords~~>~~ diceware -W 5 # 5 words		Passwords> diceware -W 5 # 5 words
	Passwords~~>~~ diceware -w wordlist.txt # custom word list		Passwords> diceware -w wordlist.txt # custom word list
	</syntaxhighlight>		</syntaxhighlight>

Line 158:		Line 158:

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

Line 165:		Line 165:

	<syntaxhighlight lang="bash" copy>		<syntaxhighlight lang="bash" copy>
	Passwords~~>~~ ls # root group: entries, then sub-groups		Passwords> ls # root group: entries, then sub-groups
	Passwords~~>~~ ls Internet # one group		Passwords> ls Internet # one group
	Passwords~~>~~ ls -R # recurse into every group		Passwords> ls -R # recurse into every group
	Passwords~~>~~ ls -f -R # one full path per line		Passwords> ls -f -R # one full path per line
	</syntaxhighlight>		</syntaxhighlight>

Line 182:		Line 182:

	<syntaxhighlight lang="bash" copy>		<syntaxhighlight lang="bash" copy>
	Passwords~~>~~ search site # entries matching a term		Passwords> search site # entries matching a term
	Passwords~~>~~ search 'title:mail' # field-qualified term		Passwords> search 'title:mail' # field-qualified term
	Passwords~~>~~ search 'has:totp' # every entry with TOTP set up		Passwords> search 'has:totp' # every entry with TOTP set up
	</syntaxhighlight>		</syntaxhighlight>

Line 208:		Line 208:

	<syntaxhighlight lang="bash" copy>		<syntaxhighlight lang="bash" copy>
	Passwords~~>~~ show site1 # default fields; the password reads PROTECTED		Passwords> show site1 # default fields; the password reads PROTECTED
	Passwords~~>~~ show -s Internet/site1 # -s: reveal protected values too		Passwords> show -s Internet/site1 # -s: reveal protected values too
	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
	</syntaxhighlight>		</syntaxhighlight>

Line 244:		Line 244:

	<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 -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 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		Passwords> clip -b github # unique title match only, no group path needed
	</syntaxhighlight>		</syntaxhighlight>

Line 262:		Line 262:

	<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> 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 # 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		OTP="$(keepassxc-cli -q show -t Passwords.kdbx site1)" # code only, outside the repl, for a scripted login
	</syntaxhighlight>		</syntaxhighlight>