Share on Facebook
Share on Twitter
Share on Discord
Share on Telegram
Intermediate
CLI and RPC
Welcome to our tutorial on CLI and RPC in Tezos. In this tutorial, we will explore the Command Line Interface (CLI) and Remote Procedure Call (RPC) in the Tezos blockchain network. The Tezos CLI and RPC provide developers with a way to interact with the Tezos network and perform operations such as creating and managing accounts, transferring tokens, and creating and interacting with smart contracts. We will also cover the basics of how to set up and use the Tezos CLI and RPC and the best practices for using them in your development. Whether you are a developer, researcher, or simply a blockchain enthusiast, this tutorial will provide valuable insights and hands-on experience in working with the Tezos CLI and RPC.
Connecting to the network
The octez-client and Tezos RPC need to connect to a Tezos node. You can connect to your own tezos node, or you can use a community node. In both cases, you can set it for the mainnet or the testnet.
You can find a list of community nodes.
Tezos RPC (Remote Procedure Call)
RPC[1] is a client-server protocol where the requesting program is the client and the program providing the service is the server.
Tezos nodes provide a JSON/RPC interface to interact with the Tezos network. Although it uses RPC and is JSON-based, it does not follow the JSON-RPC protocol.
A complete list of calls is available. Make sure to check the protocol version before you use these calls.
RPC examples
GET ‘block’
This call returns all the information about a block. But the associated metadata may not be present, it depends on the history mode and block’s distance from the head.
GET [node_url]/chains/[chain_id]/blocks/[block_id]
Here is an example, of how to get the block number 1400114 from the mainnet using ECAD Labs node:
curl https://mainnet.api.tez.ie/chains/main/blocks/1400114
To test this call, simply click the address above (or copy-paste it, to open it in your web browser). You’ll discover a pretty long JSON object. Depending on the used browser, the visualization may be better (e.g. Firefox will format the appearance to make it easier to read).
GET ‘contract storage’
This call accesses the storage of a contract.
GET [node_url]/chains/[chain_id]/blocks/[block_id]/context/contracts/[contract_id]/storage
Example to get the storage of contract KT1Hkg5qeNhfwpKW4fXvq7HGZB9z2EnmCCA9 from block 2766362 on the mainnet using ECAD Labs node:
curl https://mainnet.api.tez.ie/chains/main/blocks/2766362/context/contracts/KT1Hkg5qeNhfwpKW4fXvq7HGZB9z2EnmCCA9/storage
You can test this call exactly the same way as the “GET block” call.
octez-client (CLI)
octez-client is the official client to interact with a Tezos node via RPC. Let’s take a look at the installation and some examples.
How to install the octez-client
On Mac OS with Homebrewbrew tap serokell/tezos-packaging-stable https://github.com/serokell/tezos-packaging-stable.git
brew install tezos-client
brew tap serokell/tezos-packaging-stable https://github.com/serokell/tezos-packaging-stable.git brew install tezos-client
On Ubuntu with binaries
sudo add-apt-repository ppa:serokell/tezos && sudo apt-get update sudo apt install tezos-client -y
On Fedora with binaries
dnf copr enable -y @Serokell/Tezos && dnf update -y dnf install -y tezos-client
Connection to a node
Below we’ll connect to a community node (https://ghostnet.tezos.marigold.dev) on the Ghostnet testnet. We’ll use the --endpoint parameter to update the configuration of the Octez Client on a Ubuntu system:
octez-client --endpoint https://ghostnet.tezos.marigold.dev config update
The result should look like the lines below:
Warning:
This is NOT the Tezos Mainnet.
Do NOT use your fundraiser keys on this network.
On Ubuntu, the config file should be written in “/.octez-client/config” under your “home” folder. For example, after the last command, the all-new “config” file looks like this (with Nano):
{ "base_dir": "/home/userName/.octez-client",
"endpoint": "https://ghostnet.tezos.marigold.dev", "web_port": 8080,
"confirmations": 0 }
Account funding
To get free tez on testnet, you must first have generated a tezos account. If not, you can generate one with the following command:
octez-client gen keys my_account
You can now retrieve the generated address (the hash of the public key, it starts with tz1, tz2, or tz3) with the command:
octez-client show address my_account
The result should look like this:
Warning:
This is NOT the Tezos Mainnet.
Do NOT use your fundraiser keys on this network.
Hash: tz1VvyNvPUdypHaTgznTLSkumj9YMZxpmB9p
Public Key: edpkufA6kH6hw4ckZWWmYuLZpfwfXc9abiaEDLqH2iviFXnK9N4oct
You can now go to the testnets website, select your testnet faucet, and request tez!
Octez Client user manual and version
For global options
octez-client --help
For command options
octez-client [global options] command --help
For version information
octez-client --version
On Ubuntu, the result would look like the following:
4ca33194 (2022-08-01 11:55:43 +0200) (14.0)
Octez Client examples
Get balance
Get the balance of an account:
octez-client get balance for [account_id]
Example with our previously registered user “my_account”:
octez-client get balance for my_account
The response:
Warning:
This is NOT the Tezos Mainnet.
Do NOT use your fundraiser keys on this network.
1 ꜩ
The previous response is also a way of checking if the account is activated on the testnet (first transfer).
Get timestamp
Get the UTC of the latest downloaded block. Keep in mind, timezones may differ from your local time:
octez-client get timestamp
Result example:
Warning:
This is NOT the Tezos Mainnet.
Do NOT use your fundraiser keys on this network.
2022-10-04T13:34:00Z
List known addresses
This call only lists registered implicit accounts in your Octez client.
octez-client list known addresses
Example response:
Warning:
This is NOT the Tezos Mainnet.
Do NOT use your fundraiser keys on this network.
my_account: tz1VvyNvPUdypHaTgznTLSkumj9YMZxpmB9p (unencrypted sk known)
octez-client list known contracts
Our example:
Warning:
This is NOT the Tezos Mainnet.
Do NOT use your fundraiser keys on this network.
my_account: tz1VvyNvPUdypHaTgznTLSkumj9YMZxpmB9p