Getting started with KeyPlus

Release status: This guide follows the in-development KeyPlus 0.3 source. The previous 0.2.9 release stores data differently and does not provide the workflows described here.

Requirements

• Windows or Linux
• Python 3.10 or later for a source installation
• A desktop environment to use the PySide6 interface

macOS is not currently a supported target.

Install the development source

Clone the KeyPlus repository, create a virtual environment, and install the project. The dev extra includes the test and formatting tools.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest

On Windows, activate the environment with .venv\Scripts\activate. Package build configuration also exists for Debian, Snap, and Windows, but build configuration alone does not establish that a particular 0.3 package has been published. See Packaging and platforms.

Choose an interface

Start the interactive terminal interface:

keyplus

Start the desktop interface:

keyplus --gui
# Equivalent dedicated launcher:
keyplus-gui

Both interfaces use the same default vault and application service.

Create the first vault

When no 0.3 vault exists, the CLI asks for a new master password twice. The GUI shows a setup screen with matching password fields. A non-empty matching password creates and unlocks keyplus.vault.

KeyPlus does not implement password recovery, recovery email, escrow, or an administrative override. Losing the master password means KeyPlus cannot decrypt the vault. Keep tested encrypted backups and store the master password through an independent recovery plan appropriate to you.

After setup, add an entry with a non-empty name, domain, and password. The CLI collects the credential password through hidden input. The GUI masks it while adding or editing it.

Migrate a KeyPlus 0.2 vault

KeyPlus 0.2 used a pair of files named auth.db and vault.json in the directory from which it ran. On first CLI launch, KeyPlus checks the current directory for that exact pair. You can name a known directory explicitly:

keyplus --migrate /path/to/legacy/folder

In the GUI setup screen, select Migrate a KeyPlus 0.2 Vault and choose the folder containing both files. Migration verifies the legacy password, decrypts the old vault, writes a new 0.3 vault, and validates it before reporting success. It does not delete or modify the legacy pair.

Do not delete the old files until you have opened the new vault, checked its entries, and created a separate backup. KeyPlus intentionally does not scan arbitrary folders for legacy vaults.

Next: use the desktop interface, consult the CLI reference, or review vault and backup safety.