Command Line Tools

Recommended for Advanced Users Only

Installation#

To install the ckcc-protocol package from PyPI, use this command:

% pip install "ckcc-protocol[cli]"

This should install a new command: ckcc

CLI Usage#

The ckcc command has many subcommands and options. Please use the built-in help to find your way.

% ckcc
Usage: ckcc [OPTIONS] COMMAND [ARGS]...

Options:
  -s, --serial HEX                         Operate on specific unit (default:
                                           first found)
  -c, --socket ckcc-simulator-<pid>.sock   Operate on specific simulator
  -x, --simulator                          Connect to the simulator via Unix
                                           socket
  -P, --plaintext                          Disable USB link-layer encryption
  --help                                   Show this message and exit.

Commands:
  addr        Show the human version of an address
  auth        Indicate specific user is present (for HSM).
  backup      Creates 7z encrypted backup file after prompting user to...
  bag         Factory: set or read bag number -- single use only!
  chain       Get which blockchain (Bitcoin/Testnet) is configured.
  convert2cc  Convert existing Electrum wallet file into COLDCARD wallet...
  debug       Start interactive (local) debug session
  eval        Simulator only: eval a python statement
  exec        Simulator only: exec a python script
  get-locker  Get the value held in the Storage Locker (not Bitcoin...
  hsm         Get current status of HSM feature.
  hsm-start   Enable Hardware Security Module (HSM) mode.
  list        List all attached Coldcard devices
  local-conf  Generate the 6-digit code needed for a specific PSBT file...
  logout      Securely logout of device (will require replug to start over)
  miniscript  Miniscript related commands
  msg         Sign a short text message
  multisig    Create a skeleton file which defines a multisig wallet.
  p2sh        Show a multisig payment address on-screen.
  pass        Provide a BIP39 passphrase
  pubkey      Get the public key for a derivation path
  reboot      Reboot coldcard, force relogin and start over
  restore     Uploads 7z encrypted backup file & starts backup restore...
  sign        Approve a spending transaction by signing it on Coldcard
  test        Test USB connection (debug/dev)
  upgrade     Send firmware file (.dfu) and trigger upgrade process
  upload      Send file to Coldcard (PSBT transaction or firmware)
  user        Create a new user on the Coldcard for HSM policy (also...
  version     Get the version of the firmware installed
  xfp         Get the fingerprint for this wallet (master level)
  xpub        Get the XPUB for this wallet (master level, or any derivation)

Some useful commands follow.

Firmware Upgrade#

% ckcc upgrade --help
Usage: ckcc upgrade [OPTIONS] FIRMWARE.dfu

  Send firmware file (.dfu) and trigger upgrade process

Options:
  -s, --stop-early  Stop just before reboot
  --help            Show this message and exit.

% ckcc upgrade firmware-signed.dfu
675328 bytes (start @ 293) to send from 'firmware-signed.dfu'
Uploading  [###---------------------------------]    8%  0d 00:01:18

The upload path also accepts a raw signed binary firmware file, such as firmware-signed.bin, not only .dfu.

Sign a text message#

% ckcc msg --help
Usage: ckcc msg [OPTIONS] MESSAGE

  Sign a short text message

Options:
  -p, --path TEXT  Derivation for key to use
  -v, --verbose    Include fancy ascii armour
  -j, --just-sig   Just the signature itself, nothing more
  -s, --segwit     Address in segwit native (p2wpkh, bech32)
  -w, --wrap       Address in segwit wrapped in P2SH (p2sh-p2wpkh)
  --help           Show this message and exit.

% ckcc msg "Hello world"
Hello world                       
mp2SHbLDr5hg4tvKhaZGKzkf3GmzAuQCz1
H3wh0RIKoIcyRShkbMm5SbVoKaeMYlf4up7dvVfvP1c1N5FEXoBcjiiTNxR88ybpW3XlujHGhyCvy2/hnMtSE+c=

Sign a Spending Transaction#

% ckcc sign --help
Usage: ckcc sign [OPTIONS] PSBT_IN [PSBT_OUT]

  Approve a spending transaction by signing it on Coldcard

Options:
  -f, --finalize    Show final signed transaction, ready for transmission
  -z, --visualize   Show text of Coldcard's interpretation of the transaction
                    (does not create transaction, no interaction needed)
  -p, --pushtx URL  Broadcast transaction via provided PushTx URL. Shortcut
                    options: coldcard, mempool
  -s, --signed      Include a signature over visualization text
  -x, --hex         Write out (signed) PSBT in hexidecimal
  -6, --base64      Write out (signed) PSBT encoded in base64
  --help            Show this message and exit.

If PSBT_OUT is omitted, the signed PSBT is written to standard output.

Simulator Use#

This program can also speak to the Coldcard Simulator, if it's running on the same computer. Use the global -x flag, to connect to the simulator instead of the first Coldcard:

ckcc -x xpub

Python Library#

The ckcc-protocol package includes the python library for USB communication with the Coldcard. It can also be used with the simulator.

Linux udev support file.#

See 51-coinkite.rules

Last update: July 18, 2026