Why name a key?
If you keep two or three keys plugged in — or rotate a primary and a backup — they all
look alike to the operating system, and the path the OS assigns each one
(/dev/hidraw3 today, /dev/hidraw5 tomorrow) shifts on every
replug. A friendly name fixes that: keyroost matches it to the key's stable
serial number, so "signing-yubikey" always means the same physical key no
matter which port it's in.
This makes the device list easier to read at a glance, and it lets you target a
specific key on the command line with --name instead of hunting for the
right path.
How keyroost identifies a key
A name is bound to the key's serial number, not to a port or a slot:
- For most keys (SoloKeys, Nitrokey, and similar) the serial is the USB
iSerialNumberthe key reports to the operating system. - For keys that don't expose a USB serial (such as YubiKeys), keyroost reads the serial from a vendor management applet over the smart-card (CCID) interface instead.
Either way, matching is a plain string comparison against that serial — so a named key is recognized the moment it's connected, in any port, and is shown as "not connected" when it's absent.
Nothing is written to disk until you explicitly add a name. When you do, keyroost
saves an entry to a local keys.json file on this computer — the friendly
label plus the key's serial number — so the key can be recognized later. Merely
viewing or matching keys records nothing, and you can remove an entry at any time.
Naming a key in the app
In the keyroost desktop app, select the key you want to label and use the Name this key action next to its title (it reads Rename once a name is already set). Type a short label and confirm — the key then appears under that name in the device list, and keeps it across replugs.
Naming a key from the command line
The same registry is available from keyroostctl through the
key-name command, which has three subcommands:
add— record a friendly name for a connected key. Pass the label as the first argument; keyroost reads the connected key's serial and writes it tokeys.json. If several keys are plugged in it asks which one to name (or pass--pathto point at a specific device).list— show every configured name, its serial, and whether that key is currently connected.remove— delete a configured name by its label.
keyroostctl key-name add signing-yubikey
keyroostctl key-name list
keyroostctl key-name remove signing-yubikeyOnce a key is named, commands that target a single key accept
--name signing-yubikey to pick it out, instead of a device path that
changes between plugs.
A label is 1–64 characters of lowercase letters, digits, hyphens, and underscores
([a-z0-9_-]). Names must be unique, and each serial can carry only one
name — keyroost refuses a duplicate name or a second name for the same key.
What keyroost stores
A small keys.json registry on this computer: for each named key, the
label, the serial number, and how that serial was
obtained (USB or CCID). Naming is pure local config and matching — keyroost never
enumerates or contacts a server to do it, and removing a name deletes the entry. No
secrets, PINs, or credentials are ever part of a name.
Related
Naming works alongside everything else a key can do: