Using trezorctl commands with Trezor

Trezor Wiki/Developer/Developers guide/ Using trezorctl commands with Trezor

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

Warning: These commands are for advanced users. Please use them with caution.

See also

• Create a bulk of addresses using the trezorctl command
• Using trezorctl with passphrase

Install Python-trezor

Python-trezor requires Python 3.3 or higher and libusb 1.0. The easiest way to install it is with pip. Please ensure that the latest pip is installed before installing Python-trezor or upgrade pip by using this guide.

For Linux/Mac/BSD systems install packages:

sudo pip3 install --upgrade setuptools
sudo apt-get install python3-dev python3-pip cython3 libusb-1.0-0-dev libudev-dev
sudo pip3 install trezor[hidapi]

For Windows systems, it is also needed to install libusb and also the appropriate drivers.

You can now use the Python tools, such as changing settings in the Trezor device, signing transactions, and retrieving account info and addresses.

Since Click version 7, the underscores in commands were changed to dashes. To use the trezorctl commands with underscores, please use Click version <7 with this command:

pip3 install "click<7"

For more information, see also this GitHub page .

Python-trezor version update

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

sudo pip3 install -U trezor

Commands, options and examples

Get address

• Command : 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"

• 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

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

• Command : trezorctl wipe_device

• Description : This command resets the Trezor device to factory defaults and removes all private data.

If the device is not in the 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 the bootloader mode. If the device is in the bootloader mode and the option --bootloader is called, it will erase both the user data and firmware. If the device is in the bootloader mode and the option --bootloader is not called, it will warn the user that the device is in the 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

• Command: trezorctl firmware_update

• Description: This command downloads and installs the latest firmware on the Trezor device, the device has to be in the 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-1.4.2.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/1/trezor-1.5.0.bin

-v or --version

You can specify the firmware version you want to install.

• Example:

trezorctl firmware_update -v 1.5.0

NoteIt is possible to use only one of the options: filename, url, version.

-s or --skip-check

If skip check option is turned on, the firmware update does not perform the fingerprint check.

--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 1.6.3:

trezorctl firmware_update --fingerprint e8dbb4b7fe8384afd4c99790277c2f2f366a1a0f3957aa3545c75371a99a8fcc

Backup device

• Command: trezorctl backup_device

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

Change PIN

• Command: 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

• Command: trezorctl clear_session

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

Disable passphrase

• Command: trezorctl disable_passphrase

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

Enable passphrase

• Command: trezorctl enable_passphrase

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

Initialize device

• Command: 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.

• Options:

-t or --strength

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

• Example:

This command creates a new wallet with 18-words recovery seed.

trezorctl reset_device -t 192

-r or --passphrase-protection

This option enables the 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 recovery seed backup process - showing the seed two times on the device screen. Using this option the Trezor screen shows "Needs backup" sign after a new wallet is created.

Get features

• Command: trezorctl get_features

• Description: This command retrieves the device features and settings.

• Example of the get_features response:

Features (140 bytes) {
   bootloader_hash: 32 bytes 0x511290a8723fafe73415259d2596765406325ce24b4b80032c0b70b05d9846e9,
   device_id: 'AB7731DD981031E1CD68136C',
   flags: 0,
   imported: False,
   initialized: True,
   language: 'english',
   major_version: 1,
   minor_version: 6,
   model: '1',
   needs_backup: True,
   passphrase_cached: False,
   passphrase_protection: False,
   patch_version: 3,
   pin_cached: False,
   pin_protection: False,
   revision: 20 bytes 0xef86786ff750351ec454c7bae33b4966cfa862d7,
   vendor: 'bitcointrezor.com',
}

Get public node

• Command: 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 node public key on Trezor display.

-t or --script_type

You can specify which script type of address to use to get an xpub

address/segwit/p2shsegwit

List

• Command: trezorctl list

• Description: This command lists all the connected Trezor devices.

Load device

• Command: trezorctl load_device

• Description: This command uploads custom configuration to the device. It is possible to upload a particular recovery seed or a private key(account extended private key).

• Required options:

-m or --mnemonic

Load the device with the recovery seed (12, 18 or 24 words)

OR

-x or --xprv

Load the device with private key - account extended private key (XPRIV).

OR

-s or --slip0014

This option loads the device with the recovery seed "all all all all all all all all all all all all" used in SLIP14.

See also SLIP14 GitHub page

• Options:

-p or --pin

You set the PIN protection together with loading the seed/private key.

• Example:

trezorctl load_device -s -p "1234"

-r or --passphrase-protection

This option lets the user enable passphrase protection together with loading the seed/private key.

-l or --label

This option label lets the user name the device together with loading the seed/private key.

-i or --ignore-checksum

This option lets the user load recovery seed with ignoring checksum check.

Ping

• Command: trezorctl ping

• Description: This command sends ping message to the device, it is used 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 the sending of the ping message to the device on the device.

-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

• Command: trezorctl recovery_device

• Description: This command will start the safe recovery workflow of the wallet using the recovery seed.

• Options:

-w or --words

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

-e or --expand

This option lets the user enter only the first four letters of each mnemonic 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

scrambled or matrix

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 - check if the entered recovery seed matches the seed in the device. The result will show if the recovery seed is valid and if it matches the seed in the device. This option can be used with initialized as well as with uninitialized device.

See also User manual:Dry-run recovery

Self test

• Command: trezorctl self_test

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

Set homescreen

• Command: trezorctl set_homescreen

• Description: This command lets the user change home screen on the Trezor device.

• Options:

-f or --filename

For Trezor model T: The picture has to be in TOIF (Trezor optimized image format) format with the size of 144x144 pixels. For more information about how to create home screen for Trezor, please visit this home screen editor. For more information about the TOIF picture format, please see this GitHub page.

See also User manual:Homescreen.

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

• Example

trezorctl set_homescreen -f mynewhs.png

Set label

• Command: 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

Sign message

• Command: trezorctl sign_message

• Description: This command lets user sign message using an address of a given path.

• Required option:

-n or --address

It is needed to specify BIP32 path with sign_message command., eg. "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. 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 address/segwit/p2shsegwit

Verify message

• Command: 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+OEfZzL7WvXn02ky62yDQmFFSgxzvaijYPA2ec= ahoy

Set passphrase source

• Command: trezorctl set_passphrase_source

• Description: This command works only for Trezor Model T. It lets the user set the passphrase source. It can be set as "Always asking", "Always on device" or "Always on host".

• Options:

Always on ask: 0

trezorctl set_passphrase_source 0

This option lets the user always choose the way how to set the passphrase (host or device).

Always on device: 1

trezorctl set_passphrase_source 1

This option lets the user set the passphrase always on device.

Always on host: 2

trezorctl set_passphrase_source 2

This option lets the user set the passphrase always on host, e.g., on the user's computer.