ykman-oath

Manage OATH credentials on YubiKey devices

TLDR

Display general information about the OATH application

$ ykman oath info

Change the password used to protect OATH accounts (add --clear to remove it)

$ ykman oath access change

Add a new account (the issuer is optional)

$ ykman oath accounts add [[-i|--issuer]] [issuer] [name]

List all accounts (with their issuers)

$ ykman oath accounts list

List all accounts with their current TOTP/HOTP codes (optionally filtering the list with a keyword)

$ ykman oath accounts code [keyword]

Rename an account

$ ykman oath accounts rename [keyword] [issuer:name|name]

Delete an account

$ ykman oath accounts delete [keyword]

Delete all accounts and restore factory settings

$ ykman oath reset

SYNOPSIS

ykman oath [options...] <accounts|calculate|code|list> [<args>...]

-d FILE, --device FILE
    Specify YubiKey device by serial, USB path, or alias

-t SECONDS, --timeout SECONDS
    Touch wait timeout in seconds (-1 for indefinite)

-v, --verbose
    Increase verbosity (repeatable for more detail)

-q, --quiet
    Suppress non-essential output

DESCRIPTION

The ykman oath command, part of the YubiKey Manager CLI tool from Yubico, manages the OATH application on compatible YubiKey hardware tokens. OATH (Open AuTHentication) supports storing multiple HOTP and TOTP credentials for hardware-based two-factor authentication, replacing or supplementing phone apps like Google Authenticator.

It enables users to securely store up to 32 (or more on newer models) authentication accounts on the device itself. Key operations include listing all accounts with details like issuer, account name, type (HOTP/TOTP), algorithm (SHA1/SHA256/SHA512), digits (6/8), and period; adding new accounts by specifying secrets in hex or base32 format; generating current one-time passwords (OTPs) with optional touch confirmation; deleting accounts; and calculating OTPs from raw challenge data without storage.

This enhances security by keeping secrets on tamper-resistant hardware, supporting touch policies to prevent remote attacks, and integrating with services like GitHub, Google, and password managers. Requires USB/NFC-enabled YubiKey 5 series or equivalent with OATH app enabled.

CAVEATS

Limited to YubiKey 5 series+, Security Key Nexus 5 NFC, YubiKey Nano (OTP/OATH); max ~32-250 accounts depending on model and config; secrets must be entered manually (no QR scan in CLI); touch policy enforced per-account.

SUBCOMMANDS

list: Show all accounts.
accounts add: Add credential (e.g., --oath-type totp --issuer Google --account user@example.com 3232333832353636393732353636303031353333393935343733383930).
accounts code <name>: Generate current OTP.
calculate: Compute OTP from challenge/secret.
accounts delete <name>: Remove account.

EXAMPLE USAGE

ykman oath list
ykman oath accounts code 'Google:user@example.com' --touch
ykman oath accounts add -t totp --digits 6 --issuer Google --account user hexsecretkey

HISTORY

Introduced in YubiKey Manager 1.0 (2018) by Yubico, coinciding with YubiKey 5 launch (2017) adding native OATH-HOTP/TOTP support beyond FIDO/PIV/OTP apps; evolved to version 5.x with expanded algorithms, slots, and NFC/USB-C compatibility.