The Tezos command-line wallet
To take part in a blockchain you need a key for signing operations. You can store your keys in a wallet. The reference implementation of the Tezos blockchain, Octez, has a command-line wallet tool (octez-client). Octez runs on Linux and macOS. You can do most things with the command-line tool. If you are running a Baker, then its use is essential. Here is a “how-to” for common situations.
Note: We have redacted most of the Tezos addresses in the article.
Installing octez-client
There are various ways:
- On Debian/Ubuntu Linux, you can use packages from this site, e.g. for Debian 12:
wget https://pkgbeta.tzinit.org/debian-12/octez-client_21.0-1_amd64.deb
sudo apt install ./octez-client_21.0-1_amd64.deb
- Or you can use the packages from Serokell:
sudo add-apt-repository -y ppa:serokell/tezos
sudo apt-get update
sudo apt-get install -y tezos-client
brew tap serokell/tezos-packaging-stable https://github.com/serokell/tezos-packaging-stable.git
brew install tezos-client
- Or you can install from scratch by building the software yourself.
Reading the manual
Even die-hard command-line users read the manual (sometimes). The octez-client wallet comes with its own manual built in. You can read it using:
octez-client man
or with a paging command:
octez-client man | less
To search for a keyword, use octez-client man <keyword> - for example:
$ octez-client man bootstrapped
...
...
Miscellaneous commands:
bootstrapped
Wait for the node to be bootstrapped.
Using a node
To perform operations on the Tezos blockchain, you will need to use a node. By default, octez-client will attempt to connect to a node on the local machine. But you can specify a public node on the command-line.
octez-client --endpoint https://rpc.tzbeta.net bootstrapped
A public node is also called an RPC node. RPC stands for Remote Procedure Call. The above asks the Tezos Foundation’s RPC node if it is has started up correctly.
Using --endpoint is tedious if you want to use the same node every time, so you can set it in configuration as follows:
octez-client --endpoint https://rpc.tzbeta.net config update
But, do you trust this node to do what you want it to do? One way to be sure of trust is to use your own node. It is not difficult to set up one. You do not need to maintain a copy of the entire blockchain. A rolling node is enough to interact with it.
The disclaimer
By default, every time octez-client is run, a disclaimer is printed if it is connecting to mainnet:
$ octez-client list known addresses
Disclaimer:
The Tezos network is a new blockchain technology.
Users are solely responsible for any risks associated
with usage of the Tezos network. Users should do their
own research to determine if Tezos is the appropriate
platform for their needs and should apply judgement and
care in their network interactions.
terry: tz1...ryUZ (unencrypted sk known)
and a similar warning is printed when connecting to a test network:
$ octez-client --endpoint https://ghostnet.tezos.marigold.dev list known addresses
Warning:
This is NOT the Tezos Mainnet.
Do NOT use your fundraiser keys on this network.
terry: tz1...ryUZ (unencrypted sk known)
You should read these warnings and understand them. You can suppress them by setting an environment variable:
$ export TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=yes
$ octez-client list known addresses
terry: tz1...ryUZ (unencrypted sk known)
You can add the export line to your .bash_profile file or similar. For csh/tcsh users:
% setenv TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER yes
% octez-client list known addresses
terry: tz1...ryUZ (unencrypted sk known)
Generate a key (hot wallet)
You will need keys to take part in the Tezos network. In this section we show you how to generate keys stored on your computer in a hot wallet. This might not be a good idea, particularly if you decide to throw your computer away. Also if someone gets access to your computer, they may get access to your keys. Access to your keys is access to your wallet which is access to your funds.
When running on mainnet, octez-client will insist you protect your keys with a password to encrypt them. With password encryption your key is safer than without. But if someone gets access to your wallet, they could try to brute force the password and crack your key. When running on a test network, a hot wallet is usually good enough.
To generate a key and hence a wallet, you can use the gen keys command. This generates a hot wallet on your computer.
On mainnet, you will be asked for a password to encrypt your key:
$ octez-client gen keys christopher
Enter password to encrypt your key:
Confirm password:
We can list the addresses we know about with list known addresses. For example:
$ octez-client list known addresses
christopher: tz1YTWeSSg...8fa5yW (encrypted sk known)
On a test network, you will not be asked for an encryption password by default:
$ octez-client gen keys bob
$ octez-client list known addresses
bob: tz1VGy2...gwvWh (unencrypted sk known)
In each case you can specify the signature algorithm by using --sig. Tezos supports ed25519 (default), secp256k1, p256 and bls. You can see which is used in the hash address, respectively tz1, tz2, tz3 and tz4. For example, were we have a tz4 address with the bls signature algorithm:
$ octez-client gen keys harry --sig bls
$ octez-client list known addresses
harry: tz4JCHm.....fGRrLCCS5jMz (unencrypted sk known)
Using a key from a Ledger
A much better way to manage a key is with a Hardware Security Module. The keys are held offline on the device and the signing operations happen on the device. This is also called a cold wallet.
The Ledger is a consumer HSM designed for this purpose. You just need to plug the device into your computer when you need it.
We assume that you have set up your Ledger Nano S, S+ or X using Ledger Live and you have the Tezos Wallet application installed. If you are using the machine remotely, you may need to set the permissions on the USB device. We cover this in the article on baking along with setting up the Ledger in Ledger Live.
You need to import the key for the first time on your octez-client machine. Although we say that we import the key, it is only a reference to the key that we store. To use the key we need to connect the Ledger device.
To import the key, plug the ledger in and then issue:
octez-client list connected ledgers
This will produce output like this:
## Ledger `terry-likes-using-tezos`
Found a Tezos Baking 2.3.2 (git-description: "218cff29") application running
on Ledger Nano S Plus at [1-7:1.0].
To use keys at BIP32 path m/44'/1729'/0'/0' (default Tezos key path), use one
of:
octez-client import secret key ledger_chris "ledger://terry-likes-using-tezos/bip25519/0h/0h"
octez-client import secret key ledger_chris "ledger://terry-likes-using-tezos/ed25519/0h/0h"
octez-client import secret key ledger_chris "ledger://terry-likes-using-tezos/secp256k1/0h/0h"
octez-client import secret key ledger_chris "ledger://terry-likes-using-tezos/P-256/0h/0h"
You can pick any of the keys above, but we will use the ed25519 key. Add the key to the local wallet as follows:
octez-client import secret key ledger_chris \
"ledger://terry-likes-using-tezos/ed25519/0h/0h"
You wil be asked to verify the address on the screen on the Ledger to complete the process.
Balances
You can find out how many tz an address has with the get balance for command. Here we find the balance of one of the Tezos Foundation bakers:
$ octez-client get balance for tz3ipHZQpBBFuxv7eKoFgGnTaU3RBhnS93yY
322857.569807 tz
Aliases
We can keep addresses in our wallet that we use frequently. We can add addresses with the add address command. Here we add one of the Tezos Foundation bakers to the list.
$ octez-client add address tf2 tz3ipHZQpBBFuxv7eKoFgGnTaU3RBhnS93yY
We can refer to the baker as tf2 from now on. For example:
$ octez-client get balance for tf2
320965.299553 ꜩ
Transferring funds
Transferring funds is one of the basic operations on Tezos. Use the transfer command. Here we transfer 2tz from the ledger address to our hot wallet (see above). The client waits for the operation to be included.
$ octez-client transfer 2 from ledger_chris to christopher
Node is bootstrapped.
Estimated gas: 168.854 units (will add 0 for safety)
Estimated storage: no bytes added
Operation successfully injected in the node.
Operation hash is 'op9FMksK8....mhemFDe'
Waiting for the operation to be included...
Operation found in block: BM3j9wheDt6....Kysj9 (pass: 3, offset: 0)
This sequence of operations was run:
Manager signed operations:
From: tz1....
Fee to the baker: ꜩ0.00027
Expected counter: 101325042
Gas limit: 169
Storage limit: 0 bytes
Balance updates:
tz1.... ... -ꜩ0.00027
payload fees(the block proposer) ....... +ꜩ0.00027
Transaction:
Amount: ꜩ2
From: tz1....
To: tz1...
This transaction was successfully applied
Consumed gas: 168.788
Balance updates:
tz1... ... -ꜩ2
tz1... ... +ꜩ2
The operation has only been included 0 blocks ago.
We recommend to wait more.
Use command
octez-client wait for op9FMks...hemFDe to be included --confirmations 1 --branch BLZG....f9XRXUE
and/or an external block explorer.
(If you are using a Ledger, you will need to accept the transaction on the Ledger device.)
You can check that the transfer has been included fully by running the suggested command above.
$ octez-client wait for op9FMks...hemFDe to be included --confirmations 1 --branch BLZG....f9XRXUE
Operation found in block: BM3j9wh....Kysj9 (pass: 3, offset: 0)
Operation received 1 confirmations as of block: BLC5...KpmC
Or if you are feeling weak and need a graphical interlude, you can use a block explorer such as TzStats or TzKt.
Delegating
Baking is the process of creating new blocks on the Tezos blockchain using your coins as a stake. The stake is your bond that you will behave well on the network.
You do not have to bake to take part in the Tezos network. Instead you can delegate your coins to a public baker who will bake them on your behalf. Often they will charge a small fee, but they will give you the baking rewards.
If you do not stake your funds in some way it is like putting money into a mattress and forgetting about it. The analogy in the banking world is “interest on your savings”.
Once you have found your baker of choice, you can delegate to them on the command-line as follows:
octez-client set delegate for ledger_chris to baker_of_choice
It’s up to the public baker to pay you the rewards. Check with the public baker first to find out their payment schedule and fees.
Withdrawing delegations
If you no longer want to delegate your funds to a baker, you can withdraw them as follows:
octez-client withdraw delegate from ledger_chris
Setting a key to bake
If you are running a baker, you will need to have a wallet connected to the baking machine. Please see running a baker).
To register your key for baking, use the register key command. Here we register the Ledger account from above:
octez-client register key ledger_chris as delegate
If you are using a Ledger, you will also need to run the Tezos Baking app and set it up from the command-line:
octez-client setup ledger to bake for ledger_chris
Follow the instructions on the Ledger screen.
Using a key from a remote signer
We do not go into too much detail here. We will assume that you have a working remote signer.
The process is much the same as importing a key from a Ledger. The Octez signer offers remote signing via TCP socket, HTTP or HTTPS. There are other signers such as Signatory and Tacoinfra’s. We will assume the remote signer supports HTTP and is running on port 6732.
To import a key (e.g. tz1aUmQty…78Yxs) from the signer, use:
octez-client import secret key mycroft http://hostname-of-signer:6732/tz1aUmQty...78Yxs
Then you can use mycroft as any other key. The remote signer may prevent you from certain operations, e.g. to protect you from unwanted funds transfer.
Different client directory
By default, octez-client stores configuration and keys in a directory called .tezos-client in your home directory. In shorthand this is denoted ~/.tezos-client. You can choose a different client directory by specifying --base-dir directory to octez-client.
$ mkdir ~/othertezosdir
$ octez-client --base-dir ~/othertezosdir --endpoint https://rpc.tzbeta.net config update
$ octez-client --base-dir ~/othertezosdir gen keys other_secret_wallet
$ octez-client --base-dir ~/othertezosdir list known addresses
other_secret_wallet: tz1VQ...ksKM (unencrypted sk known)
It’s unlikely you will need to do this in practice. But it is a good way of separating test keys from production keys. It is tedious to keep typing --base-dir. You can set an environment variable to contain the client directory as follows:
$ export TEZOS_CLIENT_DIR=~/othertezosdir
$ octez-client list known addresses
other_secret_wallet: tz1VQ...ksKM (unencrypted sk known)
or if you prefer for csh/tcsh:
% setenv TEZOS_CLIENT_DIR ~/othertezosdir
% octez-client list known addresses
other_secret_wallet: tz1VQ...ksKM (unencrypted sk known)
Keeping backups
It’s important to keep a backup of your ~/.tezos-client directory because that is where your keys are. There are four key files:
- config - contains configuration such as endpoints
- public_keys - the public keys corresponding to the key pairs in your wallet
- public_key_hashs - the tz hashes of the public keys in your wallet
- secret_keys - the secret keys in your wallet, usually in encrypted form for mainnet
You can also print out the files, seal them in an envelope and keep them a vault for safekeeping. Keep the passwords for your secret keys separately.
Talking RPC
We only touch the surface of this topic. Recall that RPC stands for Remote Procedure Call. The client is able to send RPC commands to the node. To show this we first list the available RPC calls.
$ octez-client rpc list
This outputs a lot of information, so lets focus on one - the protocols.
$ octez-client rpc list /protocols
Available services:
- GET /protocols
- GET /protocols/<Protocol_hash>
- GET /protocols/<Protocol_hash>/environment
Dynamic parameter description:
<Protocol_hash>
Protocol_hash (Base58Check-encoded)
This output tells us that we can call /protocols with the GET method. We can do this with the client tool and we get a list of protocols that the node supports:
$ octez-client rpc get /protocols
[ "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK",
"ProtoDemoCounterDemoCounterDemoCounterDemoCou4LSpdT",
"ProtoDemoNoopsDemoNoopsDemoNoopsDemoNoopsDemo6XBoYp",
"ProtoGenesisGenesisGenesisGenesisGenesisGenesk612im",
"Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P",
"PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU",
...
"PtJakart2xVj7pYXJBXrqHgd82rdkLey5ZeeGwDgPp9rhQUbSqY",
"PtKathmankSpLLDALzWw7CGD2j2MtyveTwboEYokqUCP4a1LxMg",
"PtLimaPtLMwfNinJi9rCfDPWea8dFgTZ1MeJ9f1m2SRic6ayiwW",
"PtMumbai2TmsJHNGRkD8v8YDbtao7BLUC3wjASn1inAKLFCjaH1",
"PtNairobiyssHuh87hEhfVBGCVrK3WnS8Z2FT4ymB5tAa4r1nQf" ]
Note that some public nodes will restrict the calls that are allowed. To get the full functionality of RPC you should consider running your own node.
Footnote
There are many more operations you can do with octez-client. For example, we have not touched on smart contracts. The manual contains all the answers. Good luck with your journey on the command-line.
The image was designed by Iulian Thomas.