The command line

Getting started

First check that keyroostctl is installed and that your computer can see your key. If it isn't installed yet, see Install keyroost.

keyroostctl --version   # prints the version, e.g. keyroostctl 0.15.0
keyroostctl doctor      # checks this computer; never touches a key
keyroostctl             # shows the keys that are plugged in

With no command, keyroostctl lists your keys with a number each:

Connected devices

 1) Yubico    Work key  FIDO2 · OATH · PGP · PIV  12345678  USB·PC/SC+HID
 2) SoloKeys  Solo 2    FIDO2 · OATH              87654321  USB·PC/SC+HID

The badges show what each key can do. keyroostctl list shows the same keys in more technical detail. If a key is missing, run keyroostctl doctor: it checks the smart-card service and, on Linux, whether you have permission to use the key.

Every command explains itself. Add --help to any of them:

keyroostctl --help
keyroostctl oath --help
keyroostctl oath import --help

Tab completion saves typing, and even completes your key names. To set it up for bash (other shells are in the README):

keyroostctl completions bash > ~/.local/share/bash-completion/completions/keyroostctl

Choosing a key

With one key plugged in, there is nothing to choose: keyroost uses it. Every command starts by saying which key it is working on:

→ Work key · serial 12345678 · Yubico YubiKey OTP+FIDO+CCID 00 00

With several keys plugged in, keyroost asks which one you mean:

2 connected keys qualify (key with OATH):
   1) Work key, YubiKey 5 NFC, serial 12345678 Yubico YubiKey OTP+FIDO+CCID 00 00
   2) Backup key, YubiKey 5 NFC, serial 87654321 Yubico YubiKey OTP+FIDO+CCID 01 00
Select [1/2]:

To skip the question, say which key with -d (short for --device). It takes the number from the list, a serial number, or a name you gave the key:

keyroostctl oath list -d 2
keyroostctl oath list -d serial:12345678
keyroostctl oath list -d "Work key"

The numbers can change when you plug keys in and out; serials and names don't.

Naming your keys

A name like "Work key" is easier to remember than a serial number. You can keep the name on this computer, or store it on the key itself so it travels with the key.

keyroostctl name set "Work key"               # on this computer
keyroostctl name set "Work key" --store key   # on the key (asks for the FIDO PIN)
keyroostctl name list                         # every name, and where it lives
keyroostctl name clear "Work key"             # remove it, wherever it is

name list shows something like this:

  NAME        STORED         STATUS
  Work key    on the key     connected (#1)
  Backup key  this computer  not connected

A name stored on the key can be read by anyone who has the key, so don't put anything private in it. More in Naming your keys.

PINs and passwords

When a command needs a PIN, keyroost asks for it at a hidden prompt: nothing shows on screen while you type. It never takes a PIN typed into the command itself, because other programs on your computer could see it there.

PIN:

Each part of a key has its own PIN or password:

keyroostctl fido pin set              # passkeys: set the first PIN
keyroostctl fido pin change           # passkeys: change it
keyroostctl piv pin change            # certificates (PIV): the PIN
keyroostctl piv puk change            # certificates: the PUK, which unblocks the PIN
keyroostctl openpgp pin change        # OpenPGP: the user PIN
keyroostctl openpgp pin change --admin  # OpenPGP: the admin PIN
keyroostctl oath password set         # authenticator codes: an optional password
keyroostctl otp pin set               # Token2 key's code storage: an optional PIN

A new PIN is asked for twice, to catch typos. Too many wrong tries locks a PIN, so check how many you have left before guessing:

keyroostctl fido pin status    # e.g. "8 PIN attempt(s) remaining"
keyroostctl piv info           # includes the PIN tries left
keyroostctl openpgp info       # includes the PIN tries left
keyroostctl otp pin status

A blocked certificate PIN can be unblocked with the PUK (keyroostctl piv pin unblock), and a blocked OpenPGP user PIN with the admin PIN (keyroostctl openpgp pin unblock). For a forgotten passkey PIN or code password, the way back is a reset.

Passkeys (FIDO2)

Passkeys let you sign in to websites with your key instead of a password. Websites add them through your browser; keyroost lets you see and manage them.

keyroostctl fido info                # what the key supports (no PIN needed)
keyroostctl fido credential status   # how many passkeys it holds, and room for more
keyroostctl fido credential list     # which sites have a passkey on this key
keyroostctl fido credential delete <ID>   # remove one (asks first)

fido credential status answers in one line:

3 resident credential(s) stored, room for 22 more

The list shows a long id=… for each passkey; that is the ID to give fido credential delete. A deleted passkey can't be brought back, so make sure you have another way into that account first.

Settings and fingerprints:

keyroostctl fido config always-uv enable    # always ask for the PIN or a fingerprint
keyroostctl fido pin min-length set --length 8   # require longer PINs (one-way)
keyroostctl fido fingerprint add "Right thumb"   # on keys with a sensor
keyroostctl fido fingerprint list

The minimum PIN length can only go up; lowering it again takes a reset. More in FIDO2, Settings and Fingerprints.

Authenticator codes on a key

Your key can hold the 6-digit codes an authenticator app shows, so they live on the key instead of your phone. Most keys keep them in their OATH storage:

keyroostctl oath list                   # every code on the key
keyroostctl oath code GitHub:alice      # today's code for one account
keyroostctl oath add GitHub:alice       # asks for the setup key (hidden)
keyroostctl oath delete GitHub:alice    # asks first

oath list shows each account and its type:

GitHub:alice  [TOTP/SHA1]
Mail:demo@example.com  [TOTP/SHA1]

The setup key is the text a website shows next to its QR code. To add many codes at once, import them from your app.

Token2 keys with their own code storage use otp instead:

keyroostctl otp list
keyroostctl otp add --app GitHub --account alice
keyroostctl otp code --app GitHub --account alice

A Token2 Molto2 is a small device with a screen and 100 numbered slots:

keyroostctl molto list                    # slots in use, with their titles
keyroostctl molto seed set -s 5           # put a code in slot #5 (asks for the setup key)
keyroostctl molto title set -s 5 GitHub   # the name shown on the screen
keyroostctl molto sync --all              # set the clock on every slot

More in OATH, On-device OTP and Token2 Molto2.

Import codes from an authenticator app

If your codes live in an app like Aegis or 2FAS, you can copy them all onto your key at once. Export them from the app first; keyroost reads Aegis exports (including encrypted ones), 2FAS exports, lists of otpauth:// links, and QR code screenshots, including Google Authenticator's "Transfer accounts" QR.

See what would happen first. Nothing is written:

keyroostctl oath import --in aegis-export.json --dry-run

→ Work key · serial 12345678 · Yubico YubiKey OTP+FIDO+CCID 00 00
4 entries in aegis-export.json (Aegis) for Work key (serial 12345678) OATH:
  add       GitHub:alice
  add       Example:demo@example.com
  exists    Mail:alice                already on the key; left as is (--replace replaces it)
  skip      Steam:alice               Steam codes aren't supported
Holds 32 codes; 3 on the key; 2 will be added, 0 replaced, 1 left as is, 1 skipped.

If that looks right, run it again without --dry-run; keyroost asks once before it writes anything. If the export is encrypted, keyroost asks for its password; if your key has a password or PIN, it asks for that too.

Codes already on the key with the same name are left alone; add --replace to overwrite them. Codes the key can't store are skipped, with the reason shown. Running it again is safe.

Other keys work the same way:

keyroostctl otp import --in aegis-export.json                # a Token2 key's code storage
keyroostctl molto import --in codes.txt --slot 10            # a Molto2, from slot #10 on

On a Molto2, slots that are already in use are replaced, and the preview says so. Prefer the app? Drop the file onto the keyroost window. More in Importing codes.

Certificates and smart-card keys (PIV)

PIV turns your key into a smart card: it holds certificates for signing in to computers, VPNs or SSH servers. A key made on the card never leaves it; you can also bring a key and its certificate from a .p12/.pfx file.

keyroostctl piv info                                       # what is in each slot
keyroostctl piv key generate --slot 9a                     # make a new key in slot 9a
keyroostctl piv cert generate --slot 9a --subject "CN=Alice"   # give it a certificate
keyroostctl piv cert import --slot 9a --in alice.pem       # or use one from your company
keyroostctl piv cert export --slot 9a --out alice.pem      # save a copy of the certificate
keyroostctl piv key import --slot 9a --in alice.p12        # or a key + certificate from a .p12/.pfx file

A slot is a numbered place for one key: 9a is for signing in, 9c for signing documents, 9d for decrypting. Changing a slot needs the management key, a separate secret. If you never changed it, add --mgmt-key default.

keyroostctl piv key move --from 9a --to 82   # move a key to another slot
keyroostctl piv test --slot 9a               # check the key matches its certificate

piv test changes nothing: it asks the card to use the key and checks the answer against the certificate, then reports each check as passed, failed or skipped. Moving a key needs a key that supports it (for example YubiKey 5.7 and later). More in PIV.

OpenPGP

OpenPGP keys sign and encrypt email, files and git commits. keyroost sets up the card; everyday use usually happens in tools like GnuPG.

keyroostctl openpgp info                                   # keys, PIN tries, details
keyroostctl openpgp key import --generate --backup alice --name "Alice Example"
                                                           # new keys, saved first, then put on the card
keyroostctl openpgp key import --in alice.asc              # restore a backup onto a card
keyroostctl openpgp key expiry --set 2y --public alice.pub.asc     # two more years
keyroostctl openpgp key generate --slot sign --algorithm ed25519   # a key made on the card (no backup)
keyroostctl openpgp key import --slot decrypt --in my-key.pem      # an existing RSA key
keyroostctl openpgp sign --in contract.pdf --out contract.sig      # sign a file
keyroostctl openpgp url set https://example.com/alice.asc          # where your public key lives

There are three slots: sign, decrypt and auth (for logging in). Making or importing a key needs the admin PIN; using it needs the user PIN. A YubiKey also wants a touch. import --generate makes all three keys on this computer and writes three files before it touches the card: alice.asc (the backup, protected by a passphrase you choose), alice.pub.asc (the public key to share) and alice.rev.asc (a revocation certificate). Keep the backup and the revocation certificate offline. --algorithm takes rsa2048, rsa3072, rsa4096, nistp256, nistp384, nistp521, secp256k1 or ed25519 (Ed25519 for signing and logging in, X25519 for decrypting). Without it the type is ed25519 when the card lists it (or publishes no list), else rsa3072 when listed, else the first type the card lists; a type the card doesn't list is refused before any key is made. Keys expire after three years unless --expires says otherwise (never, 1y, 2y, 3y, 5y or YYYY-MM-DD; as in GnuPG, a date expires at midday UTC that day). key expiry signs the new date with the card, or with --backup alice.asc on this computer; it reads armored or binary files and writes them back armored. More in OpenPGP.

Notes stored on the key

Many passkey keys have a small storage area. keyroost can keep short notes there, such as where your backup key is, and SSH certificates. Anyone who has the key can read it without a PIN, so never store passwords or secrets there.

keyroostctl fido blob list                               # everything stored, numbered
keyroostctl fido blob add "Backup key is in the desk drawer"
keyroostctl fido blob show 1                             # one entry in full
keyroostctl fido blob edit 1 "Backup key is at the office"
keyroostctl fido blob export 1 --out note.bin            # save an entry to a file

[0] 64 bytes  key name  "Work key"
[1] 52 bytes  note      Backup key is in the desk drawer

Capacity: 116 of 1024 bytes used, 908 free

For an SSH key made on the key, keyroost can save its certificate where SSH expects it:

keyroostctl fido ssh list
keyroostctl fido ssh export --out id_ed25519_sk-cert.pub

More in Storage.

Resetting

A reset puts one part of the key back to factory condition. It erases everything in that part, and can't be undone. It is also the way back from a forgotten PIN or password.

keyroostctl fido reset      # all passkeys and the FIDO PIN (also notes and an on-key name)
keyroostctl oath reset      # all authenticator codes and the code password
keyroostctl piv reset       # all certificates, PIV keys and PINs
keyroostctl openpgp reset   # all OpenPGP keys; PINs back to 123456 / 12345678
keyroostctl otp reset       # all codes in a Token2 key's code storage
keyroostctl molto reset     # all 100 slots of a Molto2
keyroostctl factory-reset   # every part of the key at once

Before anything is erased, keyroost names the key and asks:

wipe the OATH applet on Work key (serial 12345678)? [y/N]

Anything other than y cancels. factory-reset asks you to type the word reset instead. A passkey reset over USB also asks you to unplug the key, plug it back in, and touch it; most keys only accept a reset just after they are plugged in. Accounts that used the erased passkeys or codes need to be set up again, so sign in with a backup first. More in Resetting.

Using keyroostctl in scripts

A script has no one to answer questions, so keyroost refuses to guess. Tell it everything up front:

• Which key: -d with a name or serial.
• Yes to the question: -y (or --yes). Without it, a command that would erase or replace something stops and says "add --yes".
• Secrets: env:NAME reads an environment variable, stdin reads one line of input. Never the secret itself.
• Output: --json gives machine-readable output for status and list commands.

keyroostctl fido credential status -d "Work key" --pin env:KR_PIN
pass show keys/fido-pin | keyroostctl fido credential status --pin stdin
keyroostctl oath import -d "Work key" --in codes.txt --yes
keyroostctl fido pin status --json

{
  "pin_retries": 8
}

keyroostctl exits with 0 when the command worked, 1 when it failed, and 2 when the command itself was mistyped (an unknown command or flag). Error messages go to standard error, results to standard output.

Troubleshooting

Start with keyroostctl doctor. It only checks this computer and is safe to run any time:

keyroost doctor — environment check

✓ PC/SC service reachable
✓ 1 reader(s):
    Yubico YubiKey OTP+FIDO+CCID 00 00

✓ YubiKey OTP+FIDO+CCID (/dev/hidraw1) is accessible

✓ udev rules installed (/etc/udev/rules.d/70-keyroost-fido.rules)

✓ /home/alice/.config/keyroost/keys.json is owner-only

A ✗ line says what is wrong; a – line is information. Common messages:

• no key with OATH is connected: keyroost sees no key that can do this. Check it is plugged in, and that it supports this feature.
• permission denied — install the udev rules (Linux): install the rules from the install notes, then unplug the key and plug it back in.
• PC/SC unavailable: the smart-card service isn't running. On Linux, install and start pcscd.
• the PIN was incorrect: one try was used up. keyroostctl fido pin status shows how many are left.
• … without confirmation; add --yes: the command was run without a terminal to ask on. Add --yes if you meant it.
• canceled; nothing was changed: you answered no, or pressed Ctrl-C or Ctrl-D.

Still stuck? --debug prints every message sent to and from the key. Look it over before posting it publicly, then share it in an issue:

keyroostctl --debug oath list

Every command

Each command with its one-line description, taken from keyroostctl --help. Add --help to any command for its options.

General

name

Name security keys: on this computer (keys.json) or on the key itself, where the name is visible to anyone who has the key

fido

Manage FIDO2: passkeys, PIN, fingerprints, settings, the large-blob store, SSH certificates, and reset

oath

Show codes and manage OATH (TOTP/HOTP) accounts on a security key

otp

Manage the OTP entries stored on a Token2 T2F2 / PIN+ FIDO key

openpgp

Manage the OpenPGP card applet: info, keys, sign, decrypt, PINs, cardholder details, and reset

piv

Manage the PIV (smart card) applet: info, PIN/PUK, management key, keys, and certificates

molto

Token2 Molto2 / Molto2v2 programmable TOTP token

prog

Token2 2nd-generation single-profile programmable TOTP token. Uses the token's fixed device key; no customer key is needed

← Back to overview