Documentation

For KeyMelier – see the latest release. Screenshots use fictional demo data.

The sidebar has three global areas – Backup & loss, Accounts and Settings (app settings for this computer) – and below them your keys. The tab bar of a key shows the everyday areas directly – Overview, PIN, Passkeys, Fingerprints, Authenticator, History, Key check. OpenPGP, PIV, OTP, the key settings and the technical details are in the Advanced menu at its end (also by keyboard: arrow keys, Esc). Areas a key does not support are not shown.

Install & first launch

Download the disk image (macOS), the installer (Windows) or the AppImage (Linux) from the latest release – the buttons on the home page link to them directly. Each release lists SHA-256 checksums – compare them if in doubt.

macOS

  1. Open KeyMelier-macOS.dmg and drag KeyMelier onto Applications. To update, do the same and choose Replace.
  2. Start KeyMelier from Applications. From version 1.8.2 the app is signed and notarized by Apple and opens directly. (Older versions were not notarized: macOS says it cannot verify the app – click Done, then System Settings → Privacy & Security → Open Anyway.)
  3. For the OTP slots, macOS asks for the Input Monitoring permission (see OTP slots).

Windows

  1. Run KeyMelier-Windows-Setup.exe. It installs KeyMelier (Start menu entry, uninstaller) or updates an existing installation.
  2. If SmartScreen appears: More info → Run anyway (releases are not yet code-signed).
  3. KeyMelier asks for administrator rights when it starts – Windows only lets administrators talk to FIDO keys directly.

Without installer: the …-macOS.zip and …-Windows.zip files contain the same apps.

Linux

  1. Download KeyMelier-Linux-x86_64.AppImage (ARM64: …-aarch64.AppImage), make it executable – chmod +x KeyMelier-Linux-x86_64.AppImage or in the file manager under Properties → Permissions – and start it. The AppImage is not signed – compare the SHA-256 checksum.
  2. Requirements: glibc 2.39 or newer (Ubuntu 22.04 and Debian 12 are too old) and the libraries a desktop installation already has – X11/xcb, OpenGL/EGL (Mesa), fontconfig with fonts, D-Bus, GLib, ALSA and the Wayland client libraries. Everything else, including Qt and its web engine, is inside the AppImage.
  3. Automatically tested (every release; the same file in clean containers with only these libraries, started under a virtual display): Ubuntu 24.04 and 26.04, Debian 13, Fedora 43 and openSUSE Leap 16.0 on x86-64 and ARM64, Arch Linux on x86-64. These tests cannot use a security key, USB, Wayland or a real desktop – see tested keys for results with hardware.
  4. AppImages need FUSE, which desktop distributions include. Without it: start it with --appimage-extract-and-run.
  5. Access to the key: distributions with systemd 244 or newer (practically all current ones) give the logged-in user access to FIDO keys automatically. If your key does not appear, install the udev rules that come with the AppImage: 
    ./KeyMelier-Linux-x86_64.AppImage --appimage-extract usr/share/keymelier/70-keymelier.rules
sudo install -m 644 squashfs-root/usr/share/keymelier/70-keymelier.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
    then unplug the key and plug it in again. The rules grant access only to the user at the computer, not to everyone.
  6. Authenticator, OpenPGP and PIV talk to the key as a smart card and need the PC/SC service: sudo apt install pcscd (Fedora: sudo dnf install pcsc-lite), then sudo systemctl enable --now pcscd.socket.
  7. Sync keeps its passphrase in the desktop keyring (Secret Service: GNOME Keyring, KWallet, KeePassXC). Everything else works without one.
  8. Copying codes and certificates uses wl-copy (Wayland) or xclip/xsel (X11) if installed.

Updates

When a new version is published, a notice appears in the sidebar. Download update fetches the disk image or installer for your system into Downloads, checks it against the SHA-256 checksum published with the release and opens it. You install it yourself: on macOS quit KeyMelier and drag the new version to Applications, on Windows follow the installer, on Linux quit KeyMelier and start the new AppImage from the folder that opened (it is already executable; delete the old one). KeyMelier never installs anything on its own. To check yourself, open About KeyMelier at the bottom of the sidebar and click Check for updates, or use KeyMelier → Check for Updates… in the macOS menu or the menu bar icon.

Plug in a key – it appears in the sidebar within a second. KeyMelier follows your system language (11 languages) and light/dark mode; the language can be changed at the bottom left.

First start

On the first start a short introduction explains what KeyMelier does, lets you choose whether it remembers history and contents or nothing at all, explains the platform notes (why Windows needs administrator rights, what the warnings for unsigned or not yet notarized builds mean and how to check the SHA-256 checksum) and shows how to begin. Skip it with Esc; open it again under About KeyMelier → Introduction. For no traces at all – not even saved settings – start KeyMelier with --stateless.

Overview & checks

Overview of a key: key check and account coverage, passkeys, authenticator, open tasks

The sidebar lists connected keys and, below, keys seen before – with the serial number that is usually printed or engraved on the key (hover for the full line). Read key (next to the key's name, or the small lock in the sidebar) unlocks it with the PIN and reads everything on it at once – passkeys, authenticator, OpenPGP, certificates; older keys without a passkey list are searched instead. KeyMelier never tries a PIN on its own. ⋯ holds further actions such as the CSV export.

Two statements are kept apart on purpose: the key check is about the device (authenticity, vulnerabilities, PIN), account coverage is about the accounts that depend on this key (only on this key, unclear, …). A technically flawless key can still have accounts without a backup. The overview leads with what is on the key – passkeys, authenticator accounts and open tasks; areas that were not read say "Not read" rather than showing an empty count. Below, the checks list what to improve; Fix jumps to the right place.

The key check status means:

Security & authenticity

Key check tab with advisories, function test and quantum safety

PIN

PIN tab

Set or change the FIDO2 PIN and see the remaining attempts. After 8 wrong PINs the FIDO application locks and only a reset helps. Some keys require a PIN change on first use (e.g. keys delivered with a start PIN) – KeyMelier guides you through it.

Passkeys

Passkeys grouped by website

Unlock with the PIN (or fingerprint) to list the passkeys stored on the key, grouped by website – search by website or account; Details shows the protection level and credential id. Rename or delete them (deleting asks again). Deleting a passkey here does not remove it from the website – remove it there too. The unlock is held in memory for a few minutes only.

Classic two-factor registrations (U2F) are not stored on the key and therefore do not appear in this list.

Key settings & reset

In Advanced → Key settings.

Settings tab with key options and applications per interface

Authenticator (TOTP/HOTP)

Authenticator codes with countdown

Two-factor codes stored on the key (compatible with Yubico Authenticator). Click a code to copy it. Accounts marked for touch show their code after you touch the key.

OpenPGP

OpenPGP keys, card data and PINs

Shows the signature, encryption and authentication keys on the card with fingerprint, algorithm and creation date, plus the signature counter, cardholder data and the PIN/admin PIN attempts. You can change or unblock PINs, choose whether every signature asks for the PIN, set touch policies (YubiKey) and reset OpenPGP.

Generate keys on the card

Generate OpenPGP keys form

Choose name, e-mail, algorithm (Ed25519/Cv25519 recommended) and validity, enter the PIN and admin PIN. The private keys are created on the key and never leave it. Afterwards:

  1. Save the revocation certificate somewhere safe – you need it if the key is lost.
  2. Save or copy the public key, or import it into GnuPG directly (if installed). Then gpg --card-status links it to the key.

Factory PINs: user PIN 123456, admin PIN 12345678 – change both.

PIV certificates

PIV slots with a certificate

PIV is used for smart card login on Windows and macOS, VPNs and e-mail signing. KeyMelier shows each slot's certificate with validity and warns about expiring certificates and factory defaults.

OTP slots (YubiKey)

OTP slots

A short touch triggers slot 1, a long touch slot 2. KeyMelier shows which slots are used and can program a static password or HMAC-SHA1 challenge-response (e.g. for KeePassXC – save the secret shown once to set up a backup key), swap or delete slots.

macOS: the OTP slots use the key's keyboard interface. Allow KeyMelier under System Settings → Privacy & Security → Input Monitoring, then restart KeyMelier.

History

History with key facts, what's on it and activity

Every key KeyMelier has seen stays in the sidebar with its last known state. Give it a name, see serial number, AAGUID and an activity timeline – and what's on it: passkey websites, authenticator accounts, OpenPGP keys, certificates and OTP slots, with the time they were last read. Only names are stored, never secrets or codes.

Account overview

Account overview across all keys

Accounts (top of the sidebar) lists every account across all your keys – passkeys and authenticator codes – grouped by service, with a rating for each: only on a lost key, only on one key (add it to a second one), passkey plus code on another key, codes only, account unclear, or passkey on several keys. The summary cards show the totals and work as filters (also by keyboard), together with the search; Reset filter shows everything again. The legend above the table explains the cells; header row and account column stay visible while you scroll. For problem accounts, Next step explains what to do at the service – KeyMelier cannot copy or register anything there by itself. The column headers show how many passkey slots each key has left and when it was last read.

The rating is deliberately strict. An account counts as the same only with the same website ID (rpId) and the same account name – two accounts at the same service (e.g. two Microsoft UPNs) are rated separately, and a similar-looking domain is never merged. Passkeys whose account name is unknown (older keys without the PIN) are shown as "account unclear" and are never counted as anyone's backup. A code is linked to a passkey only by an identical account name and marked as such. Keys marked as lost never count as protection.

Every cell says where the information comes from – read from the key, found by search (older keys) or imported – and when. A key that was never read shows ? ("not known") instead of "not there". For older keys that can only be searched, "not there" is shown only for a website the search actually asked and the key answered "no credentials" – websites not asked, errors and incomplete answers stay ?. Display names (e.g. "Administrator") are shown but never used to match accounts. Information older than 90 days is marked as stale.

The overview assumes that all keys belong to you. If you manage keys for several people, turn off All keys belong to me under Settings: the overview, the backup tables and the "backup on" hints are then hidden, because one person's key is not another person's backup.

KeyMelier only knows what it has read: open Passkeys and Authenticator once per key. Classic U2F registrations are not stored on the key and cannot appear. A passkey on a key is not proof that signing in at the service works.

Backup & lost keys

Backup overview of websites and accounts per key

Backup & loss (top of the sidebar) shows the three things to act on, in this order: how well your accounts are covered (Review accounts opens the account overview; the cards open it filtered), Lost a key? and Replace an old key. A line at the bottom shows the sync status.

All keys

All keys in the sidebar (with two or more keys) shows every key in one table – connection, key check, PIN, account coverage and when it was last read. Re-check all reloads the vulnerability data and metadata and rates the plugged-in keys again; Read all reads them one after another and asks for each PIN in turn (stops if you cancel).

Change the PIN on several keys sets or changes the PIN on the keys you choose, one at a time: you confirm each key with its own click and current PIN, KeyMelier stops at the first error and never tries a PIN again, and keys after an error are not touched. The same PIN on several keys means whoever knows it can use all of them – for a backup key kept elsewhere its own PIN is safer.

App settings

App settings: data on this computer, history transfer, sync

Settings in the sidebar apply to KeyMelier on this computer, for all keys: remembering what is on the keys, saving the history, "All keys belong to me", export or import of the history, and sync between computers. The settings of one key (PIN length, applications per interface, reset) are with that key under Advanced → Key settings.

Export inventory (also under Settings) saves everything KeyMelier knows – keys with passkeys, authenticator accounts, OpenPGP keys, certificates, OTP slots and the rating of every account – as JSON (complete, for further processing) or CSV (one row per item, for spreadsheets), optionally for one key or one account category. The file holds names only, never PINs or secrets, is saved readable only by you, and CSV cells that a spreadsheet would run as formulas are neutralised.

Lost-key assistant

If a key is lost, pick it in Lost a key? and mark it as lost. You get a checklist: websites to remove the key from (with the keys that still work there), authenticator accounts to set up again, OpenPGP keys to revoke and certificates to have revoked.

Replacing a key

Replacing an old key: comparison with the new key

Replace an old key (under Backup & loss) opens a guided view in four steps: 1 choose the old and the new key (with serial numbers), 2 compare, 3 sign in at each service with the new key and confirm, 4 see what is still open. Open entries only hides what is done. Each passkey, authenticator account, OpenPGP key, certificate and OTP slot of the old key carries two separate marks:

Private keys cannot be copied from one security key to another: register the new key at each service, set up authenticator accounts again (or from a QR code you kept), load OpenPGP keys only from your own backup or create new ones, and have certificates reissued. Progress is saved with the history; with history off it lasts until KeyMelier quits, and with "remember contents" off there is nothing to compare. KeyMelier never resets or deletes anything on either key – remove the old key at every service first, then reset it yourself.

Sync between computers

Sync between computers: folder, this computer and the other computers

Using KeyMelier on several computers? Under Settings → Sync between computers, pick a folder that you already sync – iCloud Drive, OneDrive, Dropbox, Syncthing or a NAS share – and set a passphrase. Do the same on every computer with the same passphrase. KeyMelier writes one file per computer into that folder and merges the files of the others every half minute ("last synced locally" means this computer read the folder and wrote its file – not that your cloud service has already delivered it everywhere): key names, history, what is on each key, lost and replacement status. The newest decision wins, including "no longer lost" and "removed from history".

Every computer only writes its own file and replaces it in one step, so two computers never write the same file. A file that is still arriving through the cloud is simply read again at the next check; an error is shown only if it stays unreadable.

The files are encrypted with your passphrase (scrypt, AES-256-GCM). Whoever can see the folder only sees random ids. The passphrase is kept in the macOS Keychain or Windows Credential Manager and cannot be recovered. Security ratings are never synced – each computer checks a key when it is plugged in there. Sync needs the saved history and is off in stateless mode.

Data, updates & privacy

Technical details

KeyMelier does not send any information about you or your keys. It downloads FIDO Alliance metadata (verified against the FIDO root and revocation lists), its own signed vulnerability database and the latest release number for an update notice. The data freshness is shown at the bottom of the Security tab; Check now updates immediately.

Stored locally in your home folder (keymelier): settings and the history. Start with --stateless to store nothing. The open-source licenses of all components are one click away next to it (Open-source licenses).

About KeyMelier

About KeyMelier dialog

Click About KeyMelier at the bottom of the sidebar (on macOS also in the KeyMelier menu) for the version, links to the website, source code and issue tracker, the open-source licenses and Check for updates.

Troubleshooting