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

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.