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.
There are various ways:
- On Debian/Ubuntu Linux, you can use packages from this site, e.g. for Debian 11:
wget https://pkgbeta.tzinit.org/deb11/17.3/octez-deb11-unoff-client_17.3-1_amd64.deb sudo apt install ./octez-deb11-unoff-client_17.3-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:
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.
--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.
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.
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
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 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
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.
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
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
$ 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)
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.
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.
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.