The Crescendo Command Line Interface (CLI) Tool provides a powerful interface for interacting with your Crescendo devices directly from the command line. This tool is built on top of the Crescendo SDK API and offers immediate access to all device management, PKI, OTP, and FIDO operations without requiring any programming.

Basic Usage

To use the Crescendo CLI, open your terminal and navigate to the directory where the CLI Tool is located.

Windows

cd "path\to\Crescendo_SDK_x.x.x\CLI Tool"

CrescendoCLI.exe <command> [options]

Or if added to PATH:

CrescendoCLI.exe <command> [options]

macOS

If installed via .pkg installer:

crescendo-cli <command> [options]

If using manual installation:

cd /path/to/Crescendo_SDK_x.x.x/CLI\ Tool/

./CrescendoCLI <command> [options]

Getting Help

The CLI Tool will provide help information for all commands and their parameters by using either the parameter --help or just -h.

General Help

For a list of all commands and general usage:

Windows:

CrescendoCLI.exe --help

CrescendoCLI.exe -h

macOS:

# If installed via .pkg:
crescendo-cli --help
crescendo-cli -h
 
# If using manual installation:
./CrescendoCLI --help
./CrescendoCLI -h

Command-Specific Help

For help with a specific command, including details about parameters:

CrescendoCLI.exe <command> -h

Example response for command piv-data-get:

Crescendo CLI Tool X.X.X
 
Usage: CrescendoCLI.exe piv-data-get --ber-tlv-tag <tag> [-p <pin> | -x <key>] [-v] [-s] [--log-level <level>] [-t
<token>] [--help]
 
Available options:
 
  --ber-tlv-tag      Required. String identification of the BER-TLV tag of the generic container object which ACR is to
                     be changed. For example, 5FC105, 5F-C1-0E, 5F C1 20.
  -p, --pin          PIN to be used for authentication. String "env" can be used to read an Environment Variable "PIN"
                     as a valid key. String "interactive" can be used to utilize the Windows interactive window for PIN
                     entering.
  -x, --xauth-key    XAUTH key to be used for authentication. String "env" can be used to read an Environment Variable
                     "XAUTH" as a valid key.
  -v, --verbose      Enable verbose (debug) logging (shortcut for --log-level DEBUG).
  -s, --silent       Enable silent logging (shortcut for --log-level SILENT), meaning nothing will get logged.
  --log-level        (Default: SILENT) Switch between different log levels. Valid options (case-insensitive) are
                     "DEBUG", "INFO", "WARN", "ERROR", "SILENT".
  --log-sensitive    (Default: false) Enable logging of sensitive data, such as PIN, PUK, XAUTH key, etc. By default,
                     all sensitive data is redacted in logs. Use with extreme caution.
  -t, --token        (Default: 0) Specify the number of given token to work with, or the name of the reader that the
                     token is connected into. All available tokens can be displayed with "CrescendoCLI.exe token-info".
  --help             Display this help screen.
  --version          Display version information.
 
Usage EXAMPLE:
CrescendoCLI.exe piv-data-get --ber-tlv-tag 5FC182 -p 123456 -v

Common Options

Most commands support these common options:

Option	Short	Description
`--pin <pin>`	`-p`	PIN for authentication. On Windows, use `INTERACTIVE` for dialog or `env` to read from environment variable
`--xauth-key <key>`	`-x`	XAUTH key for authentication. On Windows, use `INTERACTIVE` for dialog or `env` to read from environment variable
`--token <id>`	`-t`	Token identifier (index from `token-info` or case-insensitive substring of token name). Default: `0`
`--verbose`	`-v`	Enable verbose (debug) logging
`--log-level <level>`		Log level: `DEBUG`, `INFO`, `WARN`, `ERROR`, `SILENT` (default: `SILENT`). See LogLevel for more details.
`--log-sensitive`		Log sensitive information (use with caution)
`--help`	`-h`	Display command-specific help

Authentication Examples

PIN Authentication:

# Direct PIN
CrescendoCLI.exe <command> --pin 123456
 
# Interactive dialog (Windows only). On macOS, this will use terminal input.
CrescendoCLI.exe <command> --pin INTERACTIVE
 
# From environment variable
CrescendoCLI.exe <command> --pin env

XAUTH Authentication:

# Direct XAUTH key
CrescendoCLI.exe <command> --xauth-key 0123456789ABCDEF
 
# From environment variable
CrescendoCLI.exe <command> --xauth-key env

Token Selection

# Default token (first connected)
CrescendoCLI.exe <command>
 
# List all connected tokens with assigned indices
CrescendoCLI.exe token-info
 
# Use specific token by index 1
CrescendoCLI.exe <command> -t 1
 
# Use token by token-name substring
CrescendoCLI.exe <command> -t "Crescendo 4000"

token-info uses TokenDiscovery.ListAll and prints capabilities for each token (Crescendo, FIDO, or Crescendo+FIDO) together with the assigned -t index.

Logging

Logging is an essential part of troubleshooting and understanding the behavior of the CLI Tool. By default, the CLI Tool uses LogLevel.SILENT level, to not clutter the console output.

You can adjust the logging verbosity using the --log-level <level> parameter (see LogLevel for the full list of available levels and their descriptions). For convenience, the CLI Tool also provides two shortcut flags:

-v or --verbose: A shortcut for --log-level DEBUG. This enables detailed diagnostic information, ideal for in-depth troubleshooting.
-s or --silent: A shortcut for --log-level SILENT. This explicitly suppresses all log output.

The CLI Tool strictly separates its output streams to make scripting and data extraction easier:

Command Output (STDOUT): The actual result of a command - such as a retrieved certificate, public key string, or JSON response - is printed to the standard output.
Logs and Errors (STDERR): All diagnostic logs (based on your chosen LogLevel) and error messages are printed to the standard error stream.

This separation means you can safely redirect or pipe the result of a command without the data being corrupted by debug traces or informational logs. Please be aware of the PowerShell logging output issue when using non-silent log levels.

Examples

Redirecting only the logs to a file

This will print the standard command output to your console, but save all the debug trace logs to trace.txt.

PS C:\Temp> .\CrescendoCLI.exe pin-verify -p 123456 -v 2>trace.txt

Redirecting command output and logs separately

This will save the command's actual data output to cert.pem and the debug logs to trace.txt.

PS C:\Temp> .\CrescendoCLI.exe piv-cert-get --ber-tlv-tag 5FC105 -v >cert.pem 2>trace.txt

Sensitive Data Redaction in Logs

By default, the Crescendo CLI redacts sensitive information—such as PINs, OATH/XAUTH keys, and cryptographic payloads—from the console output and logs. You will see [REDACTED] in the trace instead of the actual data.

If you are troubleshooting a complex issue and need to inspect the raw APDU or CTAP-HID payloads, you can disable this redaction by passing the --log-sensitive flag alongside your logging level.

Example

CrescendoCLI.exe <command> --log-level DEBUG --log-sensitive

Using the --log-sensitive flag will print your actual secrets, PINs, and keys in plain text to the standard output. Do not use this flag in production environments, and carefully scrub your console output before sharing logs with support teams or saving them to a file.

Exit Codes

The CLI Tool uses exit codes to indicate command execution status:

Exit Code	Status	Description
`0`	Success	Command executed successfully
`-1`	Failed	General failure during command execution
`-2`	Exception	An exception occurred
`-3`	Invalid Parameters	Invalid or insufficient parameters provided
`-4`	No Tokens Found	No tokens are connected or available

Using Exit Codes in Scripts

Bash:

#!/bin/bash
crescendo-cli token-info
if [ $? -eq 0 ]; then
    echo "Success"
else
    echo "Failed"
    exit 1
fi

PowerShell:

CrescendoCLI.exe token-info
if ($LASTEXITCODE -eq 0) {
    Write-Host "Success"
} else {
    Write-Host "Failed"
    exit 1
}

List of All Available Commands

Command	Corresponding API Function	Description
`aca-props-get`	ListACAProperties	List all available ACA applet properties and options from the token in JSON format.
`pin-change`	ChangePIN	Change the existing PIN to a newly specified one.
`pin-verify`	VerifyPin	Verify the validity of entered PIN. If no PIN is entered, then the command corresponds to a `PIN VERIFY` command to determine whether the PIN code has already been verified.
`pin-reset-tries`	ResetPINTries	Reset the Token PIN try counter with PUK.
`pin-props-update`	UpdatePINProperties	Update PIN properties, such as min/max length, various counters etc.
`puk-put`	PUKPut	Put a specified PUK to the token.
`cache-read`	ReadCacheFreshness	Return data stored under tag `0x44` in a specified Cache data object `5FC151` on tokens using applet V4.
`xauth-key-put`	PutXAUTHKey	Store XAUTH key to the token.
`xauth-key-delete`	DeleteXAUTHKey	Delete existing XAUTH key from the token.
`xauth`	AuthenticateWithXAUTH	Perform External Authentication. Works for both static and dynamic XAUTH modes.
`xauth-mode-change`	ChangeXAUTHMode	Change the XAUTH challenge mode (static <-> dynamic).
`xauth-get-challenge`	GetChallenge	Get the XAUTH challenge from the token.
`otp-props-get`	ListOATHProperties	List all available OATH applet properties and options from the token in JSON format.
`otp-slot-configure`	ConfigureOATHSlot	Store OATH configuration and OATH key to the token to a specified OTP slot. Update the PSKC file, or create a new one if it does not yet exist.
`otp-pass-configure`	ConfigureStaticPassword	Configure static password on Crescendo Key V3. Update the PSKC file or create a new one if it does not yet exist.
`ocra-slot-configure`	ConfigureOCRASlot	Store OCRA configuration and OCRA key to the token to a specified OCRA slot. Update the PSKC file or create a new one if it does not yet exist.
`otp-slot-delete`	DeleteOATHSlot	Delete OATH configuration and corresponding OATH key from the token in specified OTP slot. Update the PSKC file. If no other `KeyPackage` tag is left in the PSKC file, the file will get deleted.
`otp-generate`	GenerateOTP	Generate OTP using key and configuration stored in specified OTP slot.
`ocra-authenticate`	OCRAAuthenticate	Perform an OCRA Challenge Response or Digital Signature operation with previously configured OCRA slot.
`piv-props-get`	ListPIVProperties	List all available Generic Container Objects and all PKI objects and their properties on a given token in JSON format.
`piv-key-pair-gen`	PIVGenerateKeyPair	Generate a pair of asymmetric keys using specified cryptographic mechanism.
`piv-pki-put`	PIVPutPKIData	Put PKI data (private key, certificate or both) to the token base on the user input.
`piv-key-delete`	PIVDeleteKey	Delete key object with specified Key Reference.
`piv-data-put`	PIVAddDataToDataObject	Store data under specified tag to a specified buffer (identified by BER TLV tag). The command reads content of the buffer and adds/rewrites only the specified tag. Other data in the buffer stay intact.
`piv-data-get`	PIVGetDataObjectContent	Return data stored in a given generic container object identified by the object’s BER TLV tag.
`piv-personal-info-get`	PIVGetPersonalInfo	Return PIV Personal information and identification in JSON format.
`piv-data-delete`	PIVDeleteDataFromDataObject	Delete data in a specified buffer (identified by BER TLV tag). The command reads the content of the buffer and deletes either data under the specified tag (other data in the buffer stay intact), or the entire content of the buffer.
`piv-data-raw-crypto`	PIVRawCryptoOperation	Take data from input file or input string and perform a raw cryptographic operation using a private key stored on the token at a given Key Reference. No padding to input data will be applied, meaning you are fully responsible for the proper length of the input data.
`piv-data-sign`	PIVSignData	Take data from input file or input string, create a Hash of the data and send it to the token to get the hash signed back using private key stored at given Key Reference.
`piv-pki-acr`	PIVChangePKISlotACR	Change the ACR of given empty PKI slot. The slot must be completely empty.
`piv-data-acr`	PIVChangeDataObjectACR	Change the ACR of given empty generic container object. The object must be completely empty.
`piv-cert-get`	PIVGetCertificate	Get certificate from specified buffer (identified by BER TLV tag).
`piv-cert-delete`	PIVDeleteCertificate	Remove a certificate from a specified buffer (identified by BER TLV tag). The command reads content of the buffer and removes the certificate. Then it adds a public key value derived from the certificate to make sure the ability to work with the private key is not lost. Other data in the buffer stay intact.
`ski-key-get`	GetSKITransportKey	SKI Part 1: Generate the SKI RSA3072 transport key (or just read it if it is already initialized).
`ski-data-encrypt`	EncryptKEKAndDataWithKEK	SKI Part 2: Generate a random Session KEK key. Then encrypt the Session KEK key with the RSA3k public transport key, and encrypt the key input key from user with the Session KEK. Store both results into a JSON format (in case of encrypted PIV key, the JSON would contain encrypted individual CRT components).
`fido-props-get`	ListFIDOProperties	List all available FIDO applet properties and options from the token in JSON format. The command should be run with elevated privileges. The command will not work when using Crescendo Keys inserted in USB slots.
`fido-pin-set`	FIDOSetPIN	Set the PIN used for FIDO authentication using the FIDO2 standard communication. This command requires elevated privileges.
`fido-pin-change`	FIDOChangePIN	Change the PIN used for FIDO authentication using the FIDO2 standard communication. This command requires elevated privileges.
`fido-cred-list`	FIDOListCredentials	List all discoverable FIDO credentials stored on the token. This command requires elevated privileges.
`fido-cred-delete`	FIDOCredentialManagement	Deletes a specified discoverable FIDO credential from the token. This command requires elevated privileges.
`fido-token-reset`	AuthenticatorReset	Reset all existing FIDO configuration and discoverable credentials stored on the token.
`token-reset`	ResetToken	Reset the specified token.
`token-new`	NewToken	Reset the token using only pin `–pin`, change the PIN to a specified value `–new-pin` and set default PIN properties. Then upload PUK to the card, and finally generate PIV personal data uploaded them to the PIV data object `5FC102`.
`token-info`	ListAll	General info about all connected SDK-compatible tokens, including capabilities and assigned `-t` index.
`token-cuid`	GetCUID	Get the CUID of the specified token.
`token-monitor`	StartMonitoring	Start live token monitoring process. Elevated privileges for monitoring FIDO devices and capabilities are required on Windows.