keepassxc-cli

Search entries

$ keepassxc-cli search [path/to/database_file] [name]

$ keepassxc-cli ls [path/to/database_file] [path/to/directory]

$ keepassxc-cli add [[-g|--generate]] [path/to/database_file] [entry_name]

$ keepassxc-cli rm [path/to/database_file] [entry_name]

$ keepassxc-cli clip [path/to/database_file] [entry_name]

$ keepassxc-cli clip [[-t|--totp]] [path/to/database_file] [entry_name]

$ keepassxc-cli diceware [[-W|--words]] 7

$ keepassxc-cli generate [[-lUns|--lower --upper --numeric --special]] [[-L|--length]] 16

keepassxc-cli [OPTIONS] [ARGS...]

-h, --help
    Displays help information for keepassxc-cli or a specific command.

-v, --version
    Shows the version of keepassxc-cli.

-d, --database <file>
    Specifies the KeePassXC database file (.kdbx) to use.

-k, --keyfile <file>
    Specifies a key file for database authentication.

-u, --username-env <env_var>
    Reads the database master username from the specified environment variable.

-p, --password-env <env_var>
    Reads the database master password from the specified environment variable.

-s, --security-desktop
    Prompts for the master password using a secure desktop dialog, if available on the system.

-e, --execute <command>
    Executes a single command and exits, useful for scripting without interactive prompts.

--show-password
    (Used with show command) Displays the password of an entry in plain text.

-c, --clip
    (Used with show, clip commands) Copies the retrieved information (e.g., password, username) to the system clipboard.

--otp
    (Used with show, clip commands) Retrieves and displays/clips the Time-based One-Time Password (TOTP) for an entry.

-a, --attribute <name>
    (Used with show command) Displays a specific attribute of an entry (e.g., URL, notes).

-r, --recursive
    (Used with ls command) Lists entries in sub-groups recursively.

-f, --force
    Forces an operation, for example, overwriting an existing entry or skipping prompts.

keepassxc-cli is the official command-line interface (CLI) client for KeePassXC, a free and open-source cross-platform password manager. It allows users to interact with and manage their KeePassXC database files (.kdbx) directly from the terminal, without needing the graphical user interface.

This makes it ideal for scripting, automated tasks, server environments, or users who prefer a text-based workflow. It supports a wide range of operations, including opening and unlocking databases, listing entries, retrieving usernames and passwords, adding new entries, editing existing ones, and performing various database maintenance tasks like changing the master key or performing database integrity checks. Its capabilities make it a powerful tool for secure password management in non-GUI contexts.

Security Risks: When using options like --show-password or piping sensitive information, be mindful of shell history and terminal buffers which might retain plaintext passwords. Consider using --clip to send credentials directly to the clipboard, or handle outputs carefully in scripts.

Clipboard Integration: Clipboard functionality (--clip) relies on external utilities like xclip (for X11) or wl-copy (for Wayland) being installed and accessible on your system.

Non-Interactive Usage: While powerful for scripting, keepassxc-cli is fundamentally non-interactive. Complex operations or database updates require careful scripting and validation of arguments.

Master Password Handling: Providing the master password via environment variables or command-line arguments (e.g., --password-env) should be done with extreme caution due to potential exposure to other processes or logs.

Scripting Automation: Ideal for retrieving credentials for automated tasks, such as SSH logins, API authentications, or database connections, without manual intervention.
Headless Environments: Managing passwords on servers or systems where a graphical interface is not available or desired.
Quick Lookups: For users who prefer command-line workflows for rapidly looking up or managing specific entries.
Password Generation: Utilizing the built-in password generator from the terminal for creating strong, random passwords.

Unlike the graphical KeePassXC application, keepassxc-cli typically opens and decrypts the database for each individual command execution and then closes it immediately after. This stateless operation means that repeated commands often require re-authentication (entering the master password or providing key file) unless session management or other credential passing mechanisms are employed carefully within scripts. This design enhances security by minimizing the time the database is held open and decrypted in memory.

keepassxc-cli emerged as a command-line counterpart to KeePassXC, which itself is a community fork of KeePassX, originally deriving from KeePass. The CLI tool was developed to provide programmatic access to KeePassXC databases, enabling users to manage their credentials in headless environments, integrate with shell scripts, or automate tasks without relying on the graphical user interface. Its development reflects the growing need for flexible and scriptable password management solutions, especially for power users and system administrators who require secure, automated access to their password stores.

keepassxc(1), pass(1), xclip(1), wl-copy(1)