Using trezorctl commands

Trezorctl commands are tools written in the Python programming language that can be used with a Trezor device using the command line client.

For a complete guide to using these commands please check out our dedicated page on GitHub here.

Install python-trezor

Please note that this guide was tested with python-trezor 0.11.2 on the following clean systems:

• Linux Mint 19
• Ubuntu 19.04.1 LTTS (Bionic Beaver)

It works with Trezor Model One (bootloader version 1.6.0, and firmware version 1.7.0 or higher) and Trezor Model T.

1 - Update repositories and install dependencies:

sudo apt update && sudo apt install -y python3-pip python3-dev libusb-1.0-0-dev libudev-dev

2 - Install setuptools and wheel:

pip3 install setuptools wheel

3 - Install python-trezor:

pip3 install trezor

4 - Update your $PATH by running:

source .profile

5 - Set up Udev rules on your system:

You can now use the Python tools for changing settings in the Trezor device, signing transactions, retrieving account info and addresses and much more!

python-trezor version update

You can check the latest python-trezor version on this page. To update your Python-trezor version run:

pip3 install -U trezor

Commands, options and examples

Get address

trezorctl get-address

Description: this command returns address for a specific BIP32 path and script type.

Required option: -n or --address BIP32 path eg."m/49'/0'/0'/0/0"

Other options:

• -c or --coin

Supported coin types: Bitcoin, Testnet, Bcash, Bgold, Bitcore, Bprivate, Crown, Dash, Decred, Decred Testnet, DigiByte, Dogecoin, Feathercoin, Flashcoin, Fujicoin, Groestlcoin, Groestlcoin Testnet, Koto, Litecoin, Litecoin Testnet, Monacoin, MonetaryUnit, Pesetacoin, SmartCash, Terracoin, Vertcoin, Viacoin, Zcash, Zcash Testnet, Zcoin, Zencash

• -t or --script-type

You can specify which script type of address to use to get xpub, e.g., address/segwit/p2shsegwit

• -d or --show-display

This option will display a specific address on the Trezor display.

Example:

trezorctl get-address -n "m/49'/0'/0'/0/0" -t "p2shsegwit" -d

Wiping the Trezor device

trezorctl wipe-device

Description: this command resets the Trezor device to factory defaults and removes all private data. If the device is not in bootloader mode, it will erase the user data. If the device is not in bootloader mode but the option --bootloader is called, it will tell the user to enter bootloader mode. If the device is in bootloader mode and the option --bootloader is called, it will erase both the user data and firmware. If the device is in bootloader mode and the option --bootloader is not called, it will warn the user that the device is in bootloader mode.

Options:

• -help

Show command description.

• -b or --bootloader

Wipe the device in the bootloader mode. This also erases the firmware.

Example:

trezorctl wipe-device

Firmware update

trezorctl firmware-update

Description: this command downloads and installs the selected firmware on the Trezor device, the device has to be in bootloader mode.

Options:

• --help

Show command description.

• -f or --filename

This option lets the user set the file from which the firmware should be installed. You can install a specific version of the firmware (.bin file), download it from this Github page

Example:

trezorctl firmware-update -f trezor-2.1.0.bin

• -u or --url

You directly type the url of the firmware file you want to install.

Example:

trezorctl firmware-update -u https://github.com/trezor/webwallet-data/raw/master/firmware/2/trezor-2.1.0.bin

• -v or --version

You can specify the firmware version you want to install.

Example:

trezorctl firmware-update -v 2.1.0

• --fingerprint

You can enter the fingerprint of the installed firmware when updating the firmware. It will check if the fingerprint of the version matches the entered fingerprint. If the version is not defined, the fingerprint is compared to the latest firmware fingerprint.

Example, for firmware 2.1.0:

trezorctl firmware-update 
--fingerprint bb5b0308807b45d41d1e2ab66a468152997ad69a01099789d8a35e464cde999f

Backup device

trezorctl backup-device

Description: this command shows the wallet backup (recovery seed) of the Trezor device two times. The device has to be initialized before using this command. Showing the wallet backup (recovery seed) on the device screen allows the user to properly back up the device.

Change PIN

trezorctl change-pin

Description: this command allows the user to change or remove the PIN protection of the Trezor device.

Options:

• -r or --remove

This option allows the user to remove PIN protection from the device.

Clear session

trezorctl clear-session

Description: this command clears the device session (remove cached PIN, passphrase etc.).

Disable passphrase

trezorctl disable-passphrase

Description: this command disables passphrase protection. It has to be confirmed by the user on the device.

Enable passphrase

trezorctl enable-passphrase

Description: this command enables passphrase protection. It has to be confirmed by the user on the device.

Initialize device

trezorctl reset-device

Description: this command initializes the device and generates a new seed after the new firmware is installed. It is the same process as the initialization of the device and creating a new wallet on trezor.io/start. Using this command, the user can set the length of the recovery seed on both devices, enable PIN or Passphrase protection, set the Trezor label, set a custom U2F counter or skip the backup process.

Options:

• -b or --backup_type

This option lets you choose between a traditional single BIP-39 wallet backup (recovery seed) or Multi-share / Shamir Backup.

Example:

trezorctl reset-device -b shamir -t 128

This initiates the devices using Multi-share / Shamir backup with 20-word shares. Changing the -t option to 256 will create a wallet using 33-word shares.

• -t or --strength

This option lets the user choose the version of the wallet backup (recovery seed). The options are 128 bits (12 words), 192 bits (18 words) and 256 bits (24 words). The default is 256 bits (24 words).

Example (create a new wallet with an 18-word wallet backup / recovery seed):

trezorctl reset-device -t 192

• -r or --passphrase-protection

This option enables passphrase protection after a new wallet is created.

• -p or --pin-protection

This option lets the user set a PIN before a new wallet is created.

• -l or --label

This option lets the user set a label for the device before a new wallet is created.

Example:

trezorctl reset-device -l "MyTrezor"

• -u or --u2f-counter

This option lets the user set a custom U2F counter.

• -s or --skip-backup

This option lets the user skip the backup process - showing the wallet backup (recovery seed) twice on the device screen. Using this option the Trezor screen shows the "Needs backup" sign after a new wallet is created.

Safety-checks

trezorctl set safety-checks [OPTIONS] [strict|prompt]

Description: set safety check level. Set to "strict" to get the full Trezor security. Set to "prompt" if you want to be able to allow potentially unsafe actions, such as mismatching coin keys or extreme fees. This is a power-user feature. Use with caution.

Example:

trezorctl set safety-checks prompt

Get features

trezorctl get-features

Description: this command retrieves the device features and settings.

Example of the get-features response:

device_id: '3B5328CA18BAE5F0553BCD3A',
   flags: 0,
   initialized: True,
   language: 'english',
   major_version: 2,
   minor_version: 1,
   model: 'T',
   needs_backup: False,
   no_backup: False,
   passphrase_cached: False,
   passphrase_protection: True,
   patch_version: 0,
   pin_cached: True,
   pin_protection: True,
   revision: 8 bytes b'3f0e3a33',
   unfinished_backup: False,
   vendor: 'trezor.io',

Get public node

trezorctl get-public-node

Description: this command retrieves an extended public key that can be used to create a watch-only wallet.

Required option:

• -n or --address

Example:

trezorctl get-public-node -n "m/44'/0'/0'/0/0"

Options:

• -c or --coin

Supported coin types: Bitcoin, Testnet, Bcash, Bgold, Bitcore, Bprivate, Crown, Dash, Decred, Decred Testnet, DigiByte, Dogecoin, Feathercoin, Flashcoin, Fujicoin, Groestlcoin, Groestlcoin Testnet, Koto, Litecoin, Litecoin Testnet, Monacoin, MonetaryUnit, Pesetacoin, SmartCash, Terracoin, Vertcoin, Viacoin, Zcash, Zcash Testnet, Zcoin, Zencash

• -d or --show-display

This option will display the node public key on the Trezor display.

• -t or --script-type

You can specify which script type of address to use to get an xpub e.g. address/segwit/p2shsegwit

List

trezorctl list

Description: this command lists all the connected Trezor devices.

Ping

trezorctl ping

Description: this command sends a ping message to the device, to check if the communication between computer and device works.

Example:

trezorctl ping "ahoy!"

Options:

• -b or --button-protection

This option requires the user to confirm on the device that it received the ping message.

• -p or --pin-protection

This option requires the user to enter PIN protection before sending the ping message to the device.

• -r or --passphrase-protection

This option requires the user to enter the passphrase before sending the ping message.

Recovery device

trezorctl recovery-device

Description: this command will start the safe recovery workflow of the wallet using the wallet backup (recovery seed).

Options:

• -w or --words

This option lets the user choose the number of wallet backup / recovery seed words (12, 18 or 24).

• -e or --expand

This option lets the user enter only the first four letters of each word (which is sufficient for a successful recovery).

• -p or --pin-protection

This option lets the user set the PIN before starting the recovery process.

Example:

trezorctl recovery-device -p

• -r or --passphrase-protection

This option lets the user enable passphrase protection before starting the recovery process.

• -l or --label

This option lets the user name the Trezor device before starting the recovery process.

• -t or --type

This option lets the user choose between the standard (scrambled) and advanced (matrix) recovery process.

Example:

trezorctl recovery-device -t matrix

• -d or --dry-run

This option lets the user perform dry run recovery, i.e., check if the entered wallet backup (recovery seed) matches that stored on the device. The result will show whether or not the backup is valid. This option can be used with initialized as well as with uninitialized device.

See also: Check your wallet backup (recovery seed) on Model One, Model T, Safe 3, Safe 5 and Safe 7

Self test

trezorctl self-test

Description: this command works only for Trezor Model One and in bootloader mode. It performs USB, RNG, CPU and FLASH tests. The results will show on the device screen.

Auto-lock-delay

trezorctl set auto-lock-delay

Description: this command delays the default auto-lock for a number of seconds.

Example:

trezorctl set auto-lock-delay 86400

Set homescreen

trezorctl set-homescreen

Description: this command lets the user change the home screen on the Trezor device. Options:

• -f or --filename

For the Trezor Model T: The picture has to be in TOIF (Trezor optimized image format) format with a size of 144x144 pixels.

For the Trezor One: The picture has to be 128x64 pixels.

For more information about how to create a home screen for Trezor Model One, please visit this home screen editor. For more information about the TOIF picture format, please see this GitHub page.

Example:

trezorctl set-homescreen -f mynewhs.png

Set label

trezorctl set-label

Description: this command lets the user set a new label or change the label of the Trezor device.

Required option:

• -l or --label

Example to rename your Trezor device to "Trezor Vault":

trezorctl set-label -l "Trezor Vault"

Set display rotation

trezorctl set-display-rotation

Description: this command lets the user rotate the screen orientation in desirable direction.

Required options: north or east or south or west

Example:

trezorctl set-display-rotation west

Sign message

trezorctl sign-message

Description: this command lets the user sign a message using the address of a given path.

Required option:

• -n or --address

It is necessary to specify BIP32 path with sign-message command e.g. "m/44'/0'/0'/0/0"

Example:

trezorctl sign-message -n "m/44'/0'/0'/0/0" "ahoy"

Options:

• -c or --coin

It is possible to specify which coin to use to sign a message. The default is "Bitcoin".

Example:

trezorctl sign-message -n "m/44'/0'/0'/0/0" -c "Litecoin" "ahoy"

• -t or --script-type

It is possible to specify which script type of address to use to sign a message e.g. address/segwit/p2shsegwit

Verify message

trezorctl verify-message

Description: this command lets the user verify a signed message using an address. After the command is executed, the device will ask the user to confirm the address and to verify the message.

Options:

• -c or --coin

Usage: trezorctl verify-message [OPTIONS] ADDRESS SIGNATURE MESSAGE

Example:

trezorctl verify-message 
1aWUN65K8ecrc4yi4CnWWB76SaeB8CxHt H2cYhELO9G/NES63uARBidkkgV2ARD8nhCNWHjf+rcTmJreVi+OEfZzL7WvXn02ky62yDQmFF

Set passphrase source

trezorctl set passphrase enabled --force-on-device

Description: this command works only for Trezor Model T. It forces the passphrase entry always on the device. This is useful for using Trezor with wallets that can't specify where the passphrase should be entered on.

Trezor Safe Family Bootloader Unlock

trezorctl device unlock-bootloader

Description: unlocks the Trezor device bootloader, allowing the installation of unsigned firmware by erasing the Optiga pairing secret. This bypasses secure element authenticity checks and is recommended only for advanced users.

Trezor Safe Family Tutorial

trezorctl device tutorial

Description: this will trigger the device tutorial on Trezor Safe Family devices.