keycard-cli

keycard is a command line tool to manage Status Keycards — programmable NFC/USB hardware wallets for Ethereum and other cryptographic operations.

Dependencies
Installation
Building from Source
Global Flags
Environment Variables
CLI Commands
- Lifecycle
- Pairing
- Key Management
- Signing
- Credentials
- Data
- Metadata
- Cash Applet
- Ident Applet
- Shell

Dependencies

A USB smart card reader (contact readers are more reliable than NFC readers).
On Linux, install and run the PC/SC daemon.

Installation

Download the pre-built binary for your platform from the releases page and rename the file to keycard, removing the platform-specific suffix.

Building from Source

make build
./build/bin/keycard --help

To run tests:

make test

Global Flags

The following flags are available on all commands:

Flag	Description
`--log-level <level>`	Log level: `debug`, `info`, `warn`, `error` (default: `info`)
`--pin <pin>`	PIN for card authentication (or `KEYCARD_PIN` env var)
`--puk <puk>`	PUK for card unblocking (or `KEYCARD_PUK` env var)
`--pairing-password <pw>`	Pairing password for V1 cards (or `KEYCARD_PAIRING_PASSWORD` env var)
`--reader <name>`	Specific reader name to use (auto-detect if omitted)
`--json` / `-j`	Output in JSON format
`--yes` / `-y`	Skip interactive confirmations
`--card-ca <hex>`	CA public key for V2 certificate verification (hex, 33 bytes compressed)
`--test-card`	Shortcut for `--card-ca` with the test CA public key
`--whitelist-card <hex>`	Whitelisted card identity public key (hex, 33 bytes compressed)
`--show-secrets`	Show secrets (PIN, PUK, pairing keys) in output. Hidden by default

Environment Variables

Variable	Description
`KEYCARD_PIN`	Default PIN for card authentication
`KEYCARD_PUK`	Default PUK for card unblocking
`KEYCARD_PAIRING_PASSWORD`	Default pairing password for V1 cards

CLI Commands

Lifecycle

`version`

Show the CLI version.

keycard version

`info`

Show card information (applet version, initialization status, public key, etc.).

keycard info
keycard info --json

`install`

Install applets to the card. Download the cap file from the keycard-tech/status-keycard releases page.

keycard install --applet-file PATH_TO_CAP_FILE

By default, the keycard and ident applets are installed. Control which applets get installed:

Flag	Default	Description
`--keycard-applet`	`true`	Install keycard applet
`--ident-applet`	`true`	Install ident applet
`--cash-applet`	`false`	Install cash applet
`--ndef-applet`	`false`	Install NDEF applet
`--force` / `-f`		Force reinstallation if already installed
`--ndef <url>`		URL for the NDEF record (supports `{{.cashAddress}}` variable)

`delete`

⚠️ WARNING: This command removes all applets and all keys from the card.

keycard delete --yes

`init`

Initialize the card and generate the secrets needed for authentication.

keycard init

Options:

Flag	Description
`--pin <pin>`	Set a specific PIN (random if omitted)
`--puk <puk>`	Set a specific PUK (random if omitted)
`--pairing-password <pw>`	Set pairing password (V1 only, random if omitted)
`--alt-pin <pin>`	Set alternative PIN (random if omitted)
`--pin-retries <n>`	Number of PIN retries allowed (default: 3)
`--puk-retries <n>`	Number of PUK retries allowed (default: 5)

On V2 cards (Secure Channel V2), the pairing password is not used.

`factory-reset`

⚠️ WARNING: This command erases all data from the card.

keycard factory-reset --yes

Pairing

Pairing is only needed for applet versions < 4.0 (Secure Channel V1). V2 cards use certificate-based authentication.

`pair`

Pair with the card to establish a secure channel.

keycard pair --pairing-password YOUR_PAIRING_PASSWORD

`unpair`

Unpair a specific pairing index.

keycard unpair --index 0 --pin YOUR_PIN

`unpair-all`

Remove all other pairings (keep current session).

keycard unpair-all --pin YOUR_PIN

Key Management

`generate-key`

Generate a new random key on the card.

keycard generate-key --pin YOUR_PIN

`generate-mnemonic`

Generate a BIP39 mnemonic phrase using the card's secure RNG. The phrase is returned but not loaded by default. Use --save to also load the mnemonic's seed onto the card.

keycard generate-mnemonic --words 12                           # Generate only (no PIN needed)
keycard generate-mnemonic --words 24 --save --pin YOUR_PIN     # Generate and load onto card

Flag	Default	Description
`--words <n>`	`12`	Number of words: 12, 15, 18, 21, or 24
`--save`		Also load the mnemonic's binary seed onto the card (requires PIN)

`remove-key`

Remove the current key from the card.

keycard remove-key --pin YOUR_PIN

`load-seed`

Load a BIP39 seed onto the card.

keycard load-seed --mnemonic "word1 word2 ... word12" --pin YOUR_PIN
keycard load-seed --hex "0x..." --pin YOUR_PIN

`load-lee-seed`

Load a seed for usage with the LEE (Logos Execution Environment) onto the card (applet >= 4.0 only).

keycard load-lee-seed --mnemonic "word1 word2 ... word12" --pin YOUR_PIN

`export-public-key`

Export the public key.

keycard export-public-key --path "m/44'/60'/0'/0/0" --pin YOUR_PIN

`export-private-key`

Export the private key. Only works for paths in the EIP-1581 tree.

keycard export-private-key --path "m/43'/60'/1581'/4'/1469833213'/1555737549" --pin YOUR_PIN

`export-extended-key`

Export the extended key (public key + chain code).

keycard export-extended-key --path "m/44'/60'/0'/0/0" --pin YOUR_PIN

`export-lee-key`

Export a LEE key at the given path (applet >= 4.0 only).

keycard export-lee-key --path "m/44'/60'/0'/0/0" --pin YOUR_PIN

`export-bip85`

Export a BIP85 derived key (applet >= 4.0 only).

keycard export-bip85 --path "m/83696968'/39'/0'/12'/0'" --length 16 --pin YOUR_PIN

Signing

`sign`

Sign a 32-byte hash.

keycard sign --hex "0x..." --path "m/44'/60'/0'/0/0" --algo ecdsa --pin YOUR_PIN
keycard sign --hex "0x..." --path "m/44'/60'/0'/0/0" --algo schnorr --pin YOUR_PIN

`sign-message`

Sign a message using the Ethereum Signed Message format.

keycard sign-message "Hello, Keycard!" --path "m/44'/60'/0'/0/0" --pin YOUR_PIN

`sign-file`

Sign a file (hashes the file content with Keccak256).

keycard sign-file --file /path/to/file --path "m/44'/60'/0'/0/0" --pin YOUR_PIN

Credentials

`verify-pin`

Verify the PIN.

keycard verify-pin --pin YOUR_PIN

`change-pin`

Change the PIN.

keycard change-pin --new NEW_PIN --pin YOUR_PIN

`change-puk`

Change the PUK.

keycard change-puk --new NEW_PUK --pin YOUR_PIN

`unblock-pin`

Unblock the PIN using the PUK.

keycard unblock-pin --puk YOUR_PUK --new-pin NEW_PIN

`change-pairing-password`

Change the pairing password (applet < 4.0 only).

keycard change-pairing-password --new NEW_PASSWORD --pin YOUR_PIN

Data

`get-data`

Read data from the card.

keycard get-data --type public
keycard get-data --type ndef
keycard get-data --type cash

`store-data`

Store data on the card.

keycard store-data --type public --hex "0x..." --pin YOUR_PIN
keycard store-data --type public --file /path/to/data --pin YOUR_PIN

`get-challenge`

Get a random challenge from the card (applet >= 4.0 only).

keycard get-challenge --length 32

`set-ndef`

Set the NDEF record on the card.

keycard set-ndef --hex "0x..." --pin YOUR_PIN
keycard set-ndef --file /path/to/ndef --pin YOUR_PIN

`get-status`

Get card status (PIN retries, key path, etc.).

keycard get-status

Metadata

`get-name`

Get the card's display name.

keycard get-name

`set-name`

Set the card's display name.

keycard set-name --name "My Keycard" --pin YOUR_PIN

Cash Applet

`cash-info`

Show Cash applet information.

keycard cash-info

`cash-sign`

Sign data using the Cash applet.

keycard cash-sign --hex "0x..."

Ident Applet

`load-ident`

Load an identity certificate onto the Ident applet.

keycard load-ident --hex "0x..."
keycard load-ident --test

Shell

Start an interactive shell or run a script file for batch operations.

# Interactive shell
keycard shell

# Run a script file
keycard shell -f script.sh

# Pipe commands from stdin
echo "info" | keycard shell

# JSON output (JSONL)
keycard shell -f script.sh --json

The shell supports template functions like {{env "KEYCARD_PIN"}}, {{session_pairing_key}}, {{session_pin}}, etc. See the _shell-commands-examples directory for examples.

Name		Name	Last commit message	Last commit date
Latest commit History 142 Commits
.agents/skills		.agents/skills
_assets		_assets
_shell-commands-examples		_shell-commands-examples
cmd		cmd
internal		internal
.gitignore		.gitignore
LICENSE.md		LICENSE.md
Makefile		Makefile
README.md		README.md
VERSION		VERSION
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

keycard-cli

Dependencies

Installation

Building from Source

Global Flags

Environment Variables

CLI Commands

Lifecycle

version

info

install

delete

init

factory-reset

Pairing

pair

unpair

unpair-all

Key Management

generate-key

generate-mnemonic

remove-key

load-seed

load-lee-seed

export-public-key

export-private-key

export-extended-key

export-lee-key

export-bip85

Signing

sign

sign-message

sign-file

Credentials

verify-pin

change-pin

change-puk

unblock-pin

change-pairing-password

Data

get-data

store-data

get-challenge

set-ndef

get-status

Metadata

get-name

set-name

Cash Applet

cash-info

cash-sign

Ident Applet

load-ident

Shell

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 21

Uh oh!

Contributors

Uh oh!

Languages

`version`

`info`

`install`

`delete`

`init`

`factory-reset`

`pair`

`unpair`

`unpair-all`

`generate-key`

`generate-mnemonic`

`remove-key`

`load-seed`

`load-lee-seed`

`export-public-key`

`export-private-key`

`export-extended-key`

`export-lee-key`

`export-bip85`

`sign`

`sign-message`

`sign-file`

`verify-pin`

`change-pin`

`change-puk`

`unblock-pin`

`change-pairing-password`

`get-data`

`store-data`

`get-challenge`

`set-ndef`

`get-status`

`get-name`

`set-name`

`cash-info`

`cash-sign`

`load-ident`