YubiKey Manager CLI (ykman) User Manual

Introduction

The YubiKey Manager CLI tool ykman can be used to configure all aspects of the YubiKey. This manual covers the options for each command as well as examples.

Commands

ykman

Usage:

ykman [OPTIONS] COMMAND [ARGS]...

Description: Configure your YubiKey via the command line.

Options:

-v, --version
-d, --device SERIAL
-l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL] Enable logging at given verbosity level
--log-file FILE Write logs to the given FILE instead of standard error; ignored unless --log-level is also set
-h, --help Show this message and exit.

ykman config

Usage:

ykman config [OPTIONS] COMMAND [ARGS]...

Description: Enable/Disable applications.

The applications may be enabled and disabled independently over different interfaces (USB and NFC). The configuration may also be protected by a lock code. These commands are only applicable to YubiKey 5 series devices.

Options:

-h, --help Show this message and exit.

Examples:

Disable OpenPGP over the NFC interface.

ykman config nfc -d OPGP

Enable all applications over USB.

ykman config usb -a

Set a random application lock code.

ykman config set-lock-code -g

ykman config nfc

Usage:

ykman config nfc [OPTIONS]

Description: Enable or disable applications over NFC.

Options:

-f, --force Confirm the action without prompting.
-e, --enable [OTP|U2F|OPGP|PIV|OATH|FIDO2] Enable applications.
-d, --disable [OTP|U2F|OPGP|PIV|OATH|FIDO2] Disable applications.
-a, --enable-all Enable all applications.
-D, --disable-all Disable all applications
-l, --list List enabled applications
-L, --lock-code TEXT A 16 byte lock code used to protect the application configuration.
-h, --help Show this message and exit.

ykman config set-lock-code

Usage:

ykman config set-lock-code [OPTIONS]

Description: Set or change the configuration lock code.

A lock code may be used to protect the application configuration. The lock code must be a 32 character (16 bytes) hex value.

Options:

-f, --force Confirm the action without prompting.
-l, --lock-code HEX Current lock code.
-n, --new-lock-code HEX New lock code. Conflicts with --generate.
-c, --clear Clear the lock code.
-g, --generate Generate a random lock code. Conflicts with --new-lock-code.
-h, --help Show this message and exit.

Usage:

ykman config usb [OPTIONS]

Description: Enable or disable applications over USB.

Options:

-f, --force Confirm the action without prompting.
-e, --enable [OTP|U2F|OPGP|PIV|OATH|FIDO2] Enable applications.
-d, --disable [OTP|U2F|OPGP|PIV|OATH|FIDO2] Disable applications.
-l, --list List enabled applications.
-a, --enable-all Enable all applications.
-L, --lock-code TEXT A 16 byte lock code used to protect the application configuration.
--touch-eject When set, the button toggles the state of the smartcard between ejected and inserted (CCID only).
--no-touch-eject Disable touch eject (CCID only).
--autoeject-timeout SECONDS When set, the smartcard will automatically eject after the given time. Implies --touch-eject.
--chalresp-timeout SECONDS Sets the timeout when waiting for touch for challenge-response in the OTP application.
-h, --help Show this message and exit.

ykman config usb

ykman fido

Usage:

ykman fido [OPTIONS] COMMAND [ARGS]...

Description: Manage FIDO applications.

Options:

-h, --help Show this message and exit.

Examples:

Reset the FIDO (FIDO2 and U2F) applications.

ykman fido reset

Change the FIDO2 PIN from 123456 to 942442

ykman fido set-pin -P 123456 -n 942442

ykman fido info

Usage:

ykman fido info [OPTIONS]

Description: Display status of FIDO2 application.

Options:

-h, --help Show this message and exit.

ykman fido reset

Usage:

ykman fido reset [OPTIONS]

Description: Reset all FIDO applications.

This action will wipe all FIDO credentials, including FIDO U2F credentials, on the YubiKey and remove the PIN code. The reset must be triggered immediately after the YubiKey is inserted, and requires a touch on the YubiKey.

Options:

-f, --force Confirm the action without prompting.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman fido set-pin

Usage:

ykman fido set-pin [OPTIONS]

Description: Set or change the PIN code.

The PIN must be at least 4 characters long, and supports any type of alphanumeric characters.

Options:

-P, --pin TEXT Current PIN code.
-n, --new-pin TEXT A new PIN.
--u2f Set FIPS U2F PIN instead of FIDO2 PIN
-h, --help Show this message and exit.

ykman info

Usage:

ykman info [OPTIONS]

Description: Show general information.

Displays information about the attached YubiKey such as serial number, firmware version, applications, etc.

Options:

-h, --help Show this message and exit.

ykman list

Usage:

ykman list [OPTIONS]

Description: List connected YubiKeys.

Options:

-s, --serials Output only serial numbers, one per line (devices without serial will be omitted).

Examples:

-h, --help Show this message and exit. List only the serials of the YubiKeys connected to the computer.

ykman list -s

ykman mode

Usage:

ykman mode [OPTIONS] [MODE]

Description: Manage connection modes (USB Interfaces).

Get the current connection mode of the YubiKey, or set it to MODE. MODE can be a string, such as "OTP+FIDO+CCID", or a shortened form:"o+f+c". It can also be a mode number.

Options:

--touch-eject When set, the button toggles the state of the smartcard between ejected and inserted (CCID mode only).
--autoeject-timeout SECONDS When set, the smartcard will automatically eject after the given time. Implies --touch-eject (CCID mode only).
--chalresp-timeout SECONDS Sets the timeout when waiting for touch for challenge response.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

Examples:

ykman mode otp+ccid

Enable only the CCID interface and set the smart card to eject upon touch of the metal contact on the YubiKey.

ykman mode otp+fido+ccid --touch-eject

ykman oath

Usage:

ykman oath [OPTIONS] COMMAND [ARGS]...

Description: Manage OATH application.

Options:

-p, --password TEXT Provide a password to unlock the YubiKey.
-h, --help Show this message and exit.

Examples:

List the OATH credentials.

ykman oath list

Generate an OTP for a credential containing "yubico".

ykman oath code yubico

Delete an OATH credential containing "yubico".

ykman oath delete yubico

Set a password for the OATH application.

ykman oath set-password -n Password

ykman oath add

Usage:

ykman oath add [OPTIONS] NAME [SECRET]

Description: Add a new credential.

This will add a new credential to your YubiKey.

Options:

-o, --oath-type [TOTP|HOTP] Time-based (TOTP) or counter-based (HOTP) credential. [default: TOTP]
-d, --digits [6|7|8] Number of digits in generated code. [default: 6]
-a, --algorithm [SHA1|SHA256|SHA512] Algorithm to use for code generation. [default: SHA1]
-c, --counter INTEGER Initial counter value for HOTP credentials.
-i, --issuer TEXT Issuer of the credential.
-p, --period INTEGER Number of seconds a TOTP code is valid. [default: 30]
-t, --touch Require touch on YubiKey to generate code.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman oath code

Usage:

ykman oath code [OPTIONS] [QUERY]

Description: Generate codes.

Generate codes from credentials stored on your YubiKey. Provide a query string to match one or more specific credentials. Touch and HOTP credentials require a single match to be triggered.

Options:

-H, --show-hidden Include hidden credentials.
-s, --single Ensure only a single match, and output only the code.
-h, --help Show this message and exit.

ykman oath delete

Usage:

ykman oath delete [OPTIONS] QUERY

Description: Delete a credential.

Delete a credential from your YubiKey. Provide a query string to match the credential to delete.

Options:

-f, --force Confirm deletion without prompting
-h, --help Show this message and exit.

ykman oath info

Usage:

ykman oath info [OPTIONS]

Description: Display status of OATH application.

Options:

-h, --help Show this message and exit.

ykman oath list

Usage:

ykman oath list [OPTIONS]

Description: List all credentials.

List all credentials stored on your YubiKey.

Options:

-H, --show-hidden Include hidden credentials.
-o, --oath-type Display the OATH type.
-p, --period Display the period.
-h, --help Show this message and exit.

ykman oath remember-password

Usage:

ykman oath remember-password [OPTIONS]

Description: Manage local password storage.

Store your YubiKeys password on this computer to avoid having to enter it on each use, or delete stored passwords.

Options:

-F, --forget Forget a password.
-c, --clear-all Remove all stored passwords from this computer.
-h, --help Show this message and exit.

ykman oath reset

Usage:

ykman oath reset [OPTIONS]

Description: Reset all OATH data.

This action will wipe all credentials and reset factory settings for the OATH application on the YubiKey.

Options:

-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman oath set-password

Usage:

ykman oath set-password [OPTIONS]

Description: Password protect the OATH credentials.

Allows you to set a password that will be required to access the OATH credentials stored on your YubiKey.

Options:

-c, --clear Clear the current password.
-n, --new-password TEXT Provide a new password as an argument.
-r, --remember Remember the new password on this machine.
-h, --help Show this message and exit.

ykman oath uri

Usage:

ykman oath uri [OPTIONS] [URI]

Description: Add a new credential from URI.

Use a URI to add a new credential to your YubiKey.

Options:

-t, --touch Require touch on YubiKey to generate code.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman openpgp

Usage:

ykman openpgp [OPTIONS] COMMAND [ARGS]...

Description: Manage OpenPGP application.

Options:

-h, --help Show this message and exit.

Examples:

Change the number of OpenPGP PIN and Admin PIN attempts to 5.

ykman openpgp set-pin-retries 5 5 5

Require a touch to perform OpenPGP authentication operations.

ykman openpgp touch aut on

ykman openpgp info

Usage:

ykman openpgp info [OPTIONS]

Description: Display status of OpenPGP application.

Options:

-h, --help Show this message and exit.

ykman openpgp reset

Usage:

ykman openpgp reset [OPTIONS]

Description: Reset OpenPGP application.

This action will wipe all OpenPGP data, and set all PINs to their default values.

Options:

-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman openpgp set-pin-retries

Usage:

ykman openpgp set-pin-retries [OPTIONS] PW_ATTEMPTS...

Description: Manage pin-retries.

Sets the number of attempts available before locking for each PIN.

PW_ATTEMPTS should be three integer values corresponding to the number of attempts for the PIN, Reset Code, and Admin PIN, respectively.

Options:

--admin-pin PIN
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman openpgp touch

Usage:

ykman openpgp touch [OPTIONS] KEY [POLICY]

Description: Manage touch policy for OpenPGP keys.

KEY Key slot to get/set (sig, enc or aut).

POLICY Touch policy to set (on, off or fixed).

Options:

--admin-pin PIN Admin PIN for OpenPGP.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman otp

Usage:

ykman otp [OPTIONS] COMMAND [ARGS]...

Description: Manage OTP Application.

The YubiKey provides two keyboard-based slots which can each be configured with a credential. Several credential types are supported.

A slot configuration may be write-protected with an access code. This prevents the configuration to be overwritten without the access code provided. Mode switching the YubiKey is not possible when a slot is configured with an access code.

Options:

--access-code HEX A 6 byte access code. Set to empty to use a prompt for input.
-h, --help Show this message and exit.

Examples:

Program a random HMAC-SHA1 secret to the second programmable slot.

ykman otp chalresp -g 2

Program a Yubico OTP credential to the first slot, using the serial as the public identity and random values for everythign else.

ykman otp yubiotp -S -g -G 1

ykman otp calculate

Usage:

ykman otp calculate [OPTIONS] SLOT [CHALLENGE]

Description: Perform a challenge-response operation.

Send a challenge (in hex) to a YubiKey slot with a challenge-response credential, and read the response. Supports output as a OATH-TOTP code.

Options:

-T, --totp Generate a TOTP code, use the current time as challenge.
-d, --digits [6|8] Number of digits in generated TOTP code (default is 6).
-h, --help Show this message and exit.

ykman otp chalresp

Usage:

ykman otp chalresp [OPTIONS] SLOT [KEY]

Description: Program a challenge-response credential.

If KEY is not given, an interactive prompt will ask for it.

Options:

-t, --touch Require touch on YubiKey to generate response.
-T, --totp Use a base32 encoded key for TOTP credentials.
-g, --generate Generate a random secret key. Conflicts with KEY argument.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman otp delete

Usage:

ykman otp delete [OPTIONS] SLOT

Description: Deletes the configuration of a slot.

Options:

-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman otp hotp

Usage:

ykman otp hotp [OPTIONS] SLOT [KEY]

Description: Program an HMAC-SHA1 OATH-HOTP credential.

Options:

-d, --digits [6|8] Number of digits in generated code (default is 6).
-c, --counter INTEGER Initial counter value.
--no-enter Don't send an Enter keystroke after outputting the code.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman otp info

Usage:

ykman otp info [OPTIONS]

Description: Display status of YubiKey Slots.

Options:

-h, --help Show this message and exit.

ykman otp ndef

Usage:

ykman otp ndef [OPTIONS] SLOT

Description: Select slot configuration to use for NDEF.

Options:

-h, --help Show this message and exit.

ykman otp settings

Usage:

ykman otp settings [OPTIONS] SLOT

Description: Update the settings for a slot.

Change the settings for a slot without changing the stored secret. All settings not specified will be written with default values.

Options:

-f, --force Confirm the action without prompting.
-A, --new-access-code HEX Set a new 6 byte access code for the slot. Set to empty to use a prompt for input.
--delete-access-code Remove access code from the slot.
--enter / --no-enter Should send 'Enter' keystroke after slot output. [default: True]
-p, --pacing [0|20|40|60] Throttle output speed by adding a delay (in ms) between characters emitted. [default: 0]
-h, --help Show this message and exit.

ykman otp static

Usage:

ykman otp static [OPTIONS] SLOT [PASSWORD]

Description: Configure a static password.

To avoid problems with different keyboard layouts, the following characters are allowed by default: cbdefghijklnrtuv

Use the --keyboard-layout option to allow more characters based on preferred keyboard layout.

Options:

-g, --generate Generate a random password.
-l, --length INTEGER RANGE Length of generated password.
-k, --keyboard-layout [MODHEX|US|DE] Keyboard layout to use for the static password. [default: MODHEX]
--no-enter Don't send an Enter keystroke after outputting the password.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman otp swap

Usage:

ykman otp swap [OPTIONS]

Description: Swaps the two slot configurations.

Options:

-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman otp yubiotp

Usage:

ykman otp yubiotp [OPTIONS] SLOT

Description: Program a Yubico OTP credential.

Options:

-P, --public-id MODHEX Public identifier prefix.
-p, --private-id HEX 6 byte private identifier.
-k, --key HEX 16 byte secret key.
--no-enter Don't send an Enter keystroke after emitting the OTP.
-S, --serial-public-id Use YubiKey serial number as public ID. Conflicts with --public-id.
-g, --generate-private-id Generate a random private ID. Conflicts with --private-id.
-G, --generate-key Generate a random secret key. Conflicts with --key.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman piv

Usage:

ykman piv [OPTIONS] COMMAND [ARGS]...

Description: Manage PIV application.

Options:

-h, --help Show this message and exit.

Examples:

Generate an ECC P-256 PIV key and a self-signed certificate for it in slot 9a.

ykman piv generate-key -a ECCP256 9a pubkey.pem
ykman piv generate-certificate -s "PIV Certificate" 9a pubkey.pem

Change the PUK from 12345678 to 76384512

ykman piv change-puk -p 12345678 -n 76384512

ykman piv attest

Usage:

ykman piv attest [OPTIONS] SLOT CERTIFICATE

Description: Generate a attestation certificate for a key.

Attestation is used to show that an asymmetric key was generated on the

YubiKey and therefore doesn't exist outside the device.

SLOT PIV slot with a private key to attest.

CERTIFICATE File to write attestation certificate to. Use '-' to use stdout.

Options:

-F, --format [PEM|DER] Encoding format. [default: PEM]
-h, --help Show this message and exit.

ykman piv change-management-key

Usage:

ykman piv change-management-key [OPTIONS]

Description: Change the management key.

Management functionality is guarded by a 24 byte management key. This key is required for administrative tasks, such as generating key pairs. A random key may be generated and stored on the YubiKey, protected by PIN.

Options:

-P, --pin TEXT PIN code.
-t, --touch Require touch on YubiKey when prompted for management key.
-n, --new-management-key TEXT A new management key.
-m, --management-key TEXT Current management key.
-p, --protect Store new management key on your YubiKey, protected by PIN. A random key will be used if no key is provided.
-g, --generate Generate a random management key. Implied by
--protect unless --new-management-key is also given. Conflicts with --new-management-key.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman piv change-pin

Usage:

ykman piv change-pin [OPTIONS]

Description: Change the PIN code.

The PIN can be up to 8 characters long, and supports any type of alphanumeric characters. For cross-platform compatibility, a PIN of 6 - 8 numeric digits is recommended.

Options:

-P, --pin TEXT Current PIN code.
-n, --new-pin TEXT A new PIN.
-h, --help Show this message and exit.

ykman piv change-puk

Usage:

ykman piv change-puk [OPTIONS]

Description: Change the PUK code.

If the PIN is lost or blocked it can be reset using a PUK.

Options:

-p, --puk TEXT Current PUK code.
-n, --new-puk TEXT A new PUK code.
-h, --help Show this message and exit.

ykman piv delete-certificate

Usage:

ykman piv delete-certificate [OPTIONS] SLOT

Description: Delete a certificate.

Delete a certificate from a slot on the YubiKey.

Options:

-m, --management-key TEXT The management key.
-P, --pin TEXT PIN code.
-h, --help Show this message and exit.

ykman piv export-certificate

Usage:

ykman piv export-certificate [OPTIONS] SLOT CERTIFICATE

Description: Export a X.509 certificate.

Reads a certificate from one of the slots on the YubiKey.

SLOT PIV slot to read certificate from.

CERTIFICATE File to write certificate to. Use '-' to use stdout.

Options:

-F, --format [PEM|DER] Encoding format. [default: PEM]
-h, --help Show this message and exit.

ykman piv generate-certificate

Usage:

ykman piv generate-certificate [OPTIONS] SLOT PUBLIC-KEY

Description: Generate a self-signed X.509 certificate.

A self-signed certificate is generated and written to one of the slots on the YubiKey. A private key need to exist in the slot.

SLOT PIV slot where private key is stored.

PUBLIC-KEY File containing a public key. Use '-' to use stdin.

Options:

-m, --management-key TEXT The management key.
-P, --pin TEXT PIN code.
-s, --subject TEXT A subject name for the certificate. [required]
-d, --valid-days INTEGER Number of days until the certificate expires. [default: 365]
-h, --help Show this message and exit.

ykman piv generate-csr

Usage:

ykman piv generate-csr [OPTIONS] SLOT PUBLIC-KEY CSR

Description: Generate a Certificate Signing Request (CSR).

A private key need to exist in the slot.

SLOT PIV slot where the private key is stored.

PUBLIC-KEY File containing a public key. Use '-' to use stdin.

CSR File to write CSR to. Use '-' to use stdout.

Options:

-P, --pin TEXT PIN code.
-s, --subject TEXT A subject name for the requested certificate. [required]
-h, --help Show this message and exit.

ykman piv generate-key

Usage:

ykman piv generate-key [OPTIONS] SLOT PUBLIC-KEY

Description: Generate an asymmetric key pair.

The private key is generated on the YubiKey, and written to one of the slots.

SLOT PIV slot where private key should be stored.

PUBLIC-KEY File containing the generated public key. Use '-' to use stdout.

Options:

-m, --management-key TEXT The management key.
-P, --pin TEXT PIN code.
-a, --algorithm [RSA1024|RSA2048|ECCP256|ECCP384] Algorithm to use in key generation. [default: RSA2048]
-F, --format [PEM|DER] Encoding format. [default: PEM]
--pin-policy [DEFAULT|NEVER|ONCE|ALWAYS] PIN policy for slot.
--touch-policy [DEFAULT|NEVER|ALWAYS|CACHED] Touch policy for slot.
-h, --help Show this message and exit.

ykman piv import-certificate

Usage:

ykman piv import-certificate [OPTIONS] SLOT CERTIFICATE

Description: Import a X.509 certificate.

Write a certificate to one of the slots on the YubiKey.

SLOT PIV slot to import the certificate to.

CERTIFICATE File containing the certificate. Use '-' to use stdin.

Options:

-m, --management-key TEXT The management key.
-P, --pin TEXT PIN code.
-p, --password TEXT A password may be needed to decrypt the data.
-h, --help Show this message and exit.

ykman piv import-key

Usage:

ykman piv import-key [OPTIONS] SLOT PRIVATE-KEY

Description: Import a private key.

Write a private key to one of the slots on the YubiKey.

SLOT PIV slot to import the private key to.

PRIVATE-KEY File containing the private key. Use '-' to use stdin.

Options:

-P, --pin TEXT PIN code.
-m, --management-key TEXT The management key.
--pin-policy [DEFAULT|NEVER|ONCE|ALWAYS] PIN policy for slot.
--touch-policy [DEFAULT|NEVER|ALWAYS|CACHED] Touch policy for slot.
-p, --password TEXT Password used to decrypt the private key.
-h, --help Show this message and exit.

ykman piv info

Usage:

ykman piv info [OPTIONS]

Description: Display status of PIV application.

Options:

-h, --help Show this message and exit.

ykman piv reset

Usage:

ykman piv reset [OPTIONS]

Description: Reset all PIV data.

This action will wipe all data and restore factory settings for the PIV application on your YubiKey.

Options:

-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman piv set-ccc

Usage:

ykman piv set-ccc [OPTIONS]

Description: Generate and set a CCC on the YubiKey.

Options:

-P, --pin TEXT PIN code.
-m, --management-key TEXT The management key.
-h, --help Show this message and exit.

ykman piv set-chuid

Usage:

ykman piv set-chuid [OPTIONS]

Description: Generate and set a CHUID on the YubiKey.

Options:

-P, --pin TEXT PIN code.
-m, --management-key TEXT The management key.
-h, --help Show this message and exit.

ykman piv set-pin-retries

Usage:

ykman piv set-pin-retries [OPTIONS] PIN-RETRIES PUK-RETRIES

Description: Set the number of PIN and PUK retries. NOTE: This will reset the PIN and PUK to their factory defaults.

Options:

-m, --management-key TEXT The management key.
-P, --pin TEXT PIN code.
-f, --force Confirm the action without prompting.
-h, --help Show this message and exit.

ykman piv unblock-pin

Usage:

ykman piv unblock-pin [OPTIONS]

Description: Unblock the PIN.

Reset the PIN using the PUK code.

Options:

-p, --puk TEXT
-n, --new-pin NEW-PIN
-h, --help Show this message and exit.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.