keepassxc-cli 2.1.0

CLI for KeePassXC using the browser extension protocol with biometric unlock

KeePassXC CLI

A command-line interface for KeePassXC that communicates via the browser extension protocol, supporting biometric (TouchID/fingerprint) unlock on supported platforms.

keepassxc-cli talks to a running KeePassXC instance using the same native messaging protocol used by the KeePassXC Browser extension. This means:

• Biometric unlock: On macOS with TouchID (or similar) configured in KeePassXC, you can authenticate via fingerprint rather than typing your master password.
• No master password in shell history: Authentication happens through KeePassXC's GUI, not the terminal.
• CRUD: Add, edit, delete entries and groups.
• TOTP: Retrieve time-based one-time passwords.
• Clipboard: Copy credentials directly to the clipboard.

KeePassXC CLI based on KeePassXC Browser API.

Prerequisites

• macOS (uses Unix sockets and KeePassXC's browser extension socket)
• Python >= 3.10
• KeePassXC with:
  • Browser Integration enabled (Settings > Browser Integration > Enable browser integration)

Install

Homebrew (recommended)

See homebrew homepage on how to setup homebrew.

brew install mietzen/tap/keepassxc-cli

pipx

pipx install keepassxc-cli

Setup

Before using keepassxc-cli, associate it with your KeePassXC instance:

keepassxc-cli setup

This performs a key exchange with KeePassXC (you will be prompted to allow the association in the KeePassXC GUI). The association is saved to ~/.keepassxc/browser-api.json.

Usage

Global options

keepassxc-cli [--config PATH] [--browser-api-config PATH] [-v] COMMAND [COMMAND OPTIONS]

Option	Description
--config	Path to CLI config file (default: ~/.keepassxc/cli.json)
--browser-api-config	Path to browser API config file (default: ~/.keepassxc/browser-api.json)
-v, --verbose	Enable verbose/debug logging

Some commands support a -j / --json flag for JSON output — pass it anywhere after the subcommand name:

keepassxc-cli show https://github.com -j
keepassxc-cli status -j

Commands

URL scheme: All commands that accept a URL argument require a scheme (https:// or http://). If you pass a bare hostname (e.g. example.com), the CLI will automatically prepend https:// and emit a warning. KeePassXC derives the entry title from QUrl(url).host(), which returns an empty string for URLs without a scheme.

setup — Associate with KeePassXC

keepassxc-cli setup

status — Connection and association status

keepassxc-cli status
keepassxc-cli status -j

show — Show entries for a URL

keepassxc-cli show https://github.com
keepassxc-cli show https://github.com -p     # reveal password and TOTP
keepassxc-cli show https://github.com -j

Without -p, password and TOTP are omitted from the output entirely.

totp — Get TOTP code

keepassxc-cli totp https://github.com
keepassxc-cli totp https://github.com -j

clip — Copy a field to clipboard

keepassxc-cli clip https://github.com password
keepassxc-cli clip https://github.com username
keepassxc-cli clip https://github.com totp

Note: clip does not support -j/--json output — the field value is always copied silently to the clipboard.

add — Add a new entry

# Password is prompted securely if --password is not given
keepassxc-cli add https://example.com [e-mail]
keepassxc-cli add https://example.com user --password mypass
# Place the entry in a specific group by UUID or by path
keepassxc-cli add https://example.com user --group-uuid <group-uuid>
keepassxc-cli add https://example.com user --group "Work/Projects"

Note: The entry title is always derived from the URL hostname by KeePassXC. The protocol has no field to set a custom title.

edit — Edit an entry

# URL is positional; --uuid is optional when the URL matches exactly one entry
keepassxc-cli edit https://github.com --username newuser
keepassxc-cli edit https://github.com --password newpass
# Specify --uuid explicitly when the URL matches multiple entries
keepassxc-cli edit https://github.com --uuid <uuid> --username newuser

rm — Delete an entry

keepassxc-cli rm https://example.com         # prompts for confirmation
keepassxc-cli rm https://example.com --yes   # skip confirmation
# Specify --uuid when URL matches multiple entries
keepassxc-cli rm https://example.com --uuid <uuid> --yes

lock — Lock the database

keepassxc-cli lock
keepassxc-cli lock -j

unlock — Unlock the database

keepassxc-cli unlock
keepassxc-cli unlock -j

Triggers biometric (TouchID/fingerprint) unlock if configured. Raises an error if the unlock times out or KeePassXC is not running.

mkdir — Create a group

keepassxc-cli mkdir "Work"
keepassxc-cli mkdir "Work/Projects"   # create Projects inside Work

Use /-separated paths to create nested groups. KeePassXC creates any missing path segments automatically.

group-uuid — Look up a group's UUID by path

keepassxc-cli group-uuid "Work"
keepassxc-cli group-uuid "Work/Projects"
keepassxc-cli group-uuid "Work/Projects" -j

Returns the UUID for the group at the given path (relative to the database root). Useful for scripting — pipe the UUID into add --group-uuid.

JSON output (-j):

{
  "path": "Work/Projects",
  "name": "Projects",
  "uuid": "<uuid>"
}

version — Show the CLI version

keepassxc-cli version
keepassxc-cli version -j

Does not require a running KeePassXC instance.

Configuration

CLI config (~/.keepassxc/cli.json)

Only non-default values are stored. Available options:

Key	Default	Description
browser_api_config_path	~/.keepassxc/browser-api.json	Path to the browser API config
default_format	table	Default output format (table or json)

Example ~/.keepassxc/cli.json:

{
  "default_format": "json"
}

Browser API config (~/.keepassxc/browser-api.json)

Shared with keepassxc-browser-api. Contains the association keys created during keepassxc-cli setup. This file is automatically created and updated by the setup command.

Both config files are stored with 0o600 permissions (owner read/write only).

Exit codes

Code	Meaning
0	Success
1	Generic error (unexpected KeePassXC error, OS error, config parse error)
2	KeePassXC is not running or the socket is not found (ConnectionError)
3	Database unlock timed out (DatabaseLockedError)
4	Access denied by user — either the access prompt was cancelled or "Allow access to all entries" was denied

These codes are stable and suitable for scripting, e.g.:

keepassxc-cli show https://example.com || case $? in
  2) echo "Start KeePassXC first" ;;
  3) echo "Unlock timed out" ;;
  4) echo "Access denied" ;;
esac

Development

This package depends on keepassxc-browser-api, which handles the KeePassXC browser extension protocol. The browser API credentials are stored in ~/.keepassxc/browser-api.json and are shared with keepassxc-ssh-agent if installed.

git clone https://github.com/mietzen/keepassxc-cli
git clone https://github.com/mietzen/keepassxc-browser-api
cd keepassxc-cli

python3 -m venv .venv
source .venv/bin/activate

# Install local keepassxc-browser-api dependency first
pip install ../mietzen-keepassxc-browser-api/

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest --tb=short -q

# Run tests with coverage
pytest --cov=keepassxc_cli --cov-report=term-missing

# Lint
ruff check --ignore=E501 --exclude=__init__.py ./keepassxc_cli

Verify with manual tests.

---

Exit codes

Scenario	Expected code
Any successful command	0
Entry not found / generic error	1
KeePassXC not running	2
Unlock timed out	3
Access denied by user	4

keepassxc-cli show https://test.example.com; echo "exit: $?"    # 0
keepassxc-cli show https://ghost.example.com; echo "exit: $?"   # 1
# Quit KeePassXC, then:
keepassxc-cli status; echo "exit: $?"                           # 2

---

Known Limitations

• Requires KeePassXC to be running and the database to be open (or biometric auto-unlock configured).
• The clip command requires pyperclip and a working clipboard (e.g., xclip/xsel on Linux, built-in on macOS/Windows).
• The browser integration protocol does not support moving entries between groups directly.
• Entry lookup is by URL/hostname only (same as the browser extension). Title-based search is not supported by the protocol.
• String fields (string_fields in JSON output) require the KeePassXC setting "Support KPH fields" to be enabled, and custom attributes must be prefixed with KPH: in the KeePassXC entry's "Advanced" tab. This is a server-side KeePassXC requirement, not something the CLI can control.