It has been a while since I wrote a technical post due to all the excitement around various EOS issues, so I thought I would get back to my roots.
Preface
I am just going to discuss basic cleos usage in this post as it can become quite a lengthy discussion with all the potential rabbit holes you can follow, but feel free to ask questions below. I understand that keos integration is a key competent of account management (excuse the pun), I will cover the keos app in a separate post later. For those who do not know, keos is the cli wallet written by EOSIO and is seen as the most secure wallet due to that fact.
Installing cleos
As of this writing, there is no way to install cleos as a separate executable; you need to build the entire EOSIO software which bundles in cleos. Although this is not an ideal situation, it is not difficult at all; Block One has written a walkthrough that can be found here. There is a community initiative to create a build script for cleos and keos but that has only just started.
What Is cleos And How Can I Use It?
The cleos application is a command line tool written by Block One that allows you to interface with any EOS blockchain via the REST API standard. EOS Nodes such as block producers will be running the nodeos program to produce blocks on the chain, and if they started the nodeos process using the 'eosio::chain_api_plugin' flag at startup, they should also be presenting a public API to the world, firewalls permitting. Nodes are generally but not limited to block producers; anyone can run a full node, but you cannot simply jump in and start producing blocks and get paid like PoW systems.
Choose Your Endpoint
There three situations to consider when using cleos, these are:
- Do you want to connect to a local node you are running yourself?
- Do you want to connect to the EOS test net known as the Junglenet?
- Do you want to connect to the live EOS chain?
Option 1 above removes the need for the -u or --url flag that allows you to define a remote endpoint. The default behavior of cleos is set to connect to the address localhost on port number 8888, so if you have nodeos running locally, you are good to go.
Once you have decided which chain you want to work with, you will need to find an endpoint running nodes (the main EOSIO program) that are also presenting a public API for you to query against, here is a list of a few testnet and main net nodes.
| URL | HTTP Port | Full URL with Port |
|---|---|---|
| api.eosnewyork.io | 443 | https://api.eosnewyork.io:443/ |
| api.eosdetroit.io | 443 | https://api.eosdetroit.io:443/ |
| api.eosmetal.io | 18890 | https://api.eosmetal.io:18890 |
| URL | HTTP Port | Full URL with Port |
|---|---|---|
| bp4-d3.eos42.io | 8888 | http://bp4-d3.eos42.io:8888/ |
| bpseoul.eosnodeone.io | 8888 | http://bpseoul.eosnodeone.io:8888/ |
| testnet.eosindia.io | 8888 | http://testnet.eosindia.io:8888/ |
Using cleos
Once you have chosen your endpoint and know the address and port details, you will then be able to access the chain from the cli. If you want to interact with your tokens in any way, including sending, managing resources or voting, then you will also need keod running which is the cli based wallet that is also provided in the software package.
Let's look at query the chain for an account on the mainnet, here is the command and the output.
cleos -u https://api.eosnewyork.io:443 get account gm2diobtgmge
permissions:
owner 1: 1 EOS6Yh5u2FtTwGH9wbQ8VosjdYAEbifu1tBjMNyBgJEV3srrpgeKF
active 1: 1 EOS6Yh5u2FtTwGH9wbQ8VosjdYAEbifu1tBjMNyBgJEV3srrpgeKF
memory:
quota: 7.812 Kb used: 6.85 Kb
net bandwidth:
staked: 1500.0000 EOS (total stake delegated from account to self)
delegated: 0.0000 EOS (total staked delegated to account from others)
used: 1.378 Kb
available: 773.5 Mb
limit: 773.5 Mb
cpu bandwidth:
staked: 1500.0000 EOS (total stake delegated from account to self)
delegated: 0.0000 EOS (total staked delegated to account from others)
used: 67.66 ms
available: 0.04295 hr
limit: 0.04297 hr
producers:
aus1genereos cryptolions1 cypherglasss
eos42freedom eosafricaone eosamsterdam
eosasia11111 eosauthority eoscafeblock
eoscanadacom eosdacserver eosdublinwow
eoseouldotio eosiodetroit eosiomeetone
eosisgravity eosliquideos eosnationftw
eosnewyorkio eosnodeonebp eosonoeosono
eospaceioeos eosriobrazil eossv12eossv
eostribeprod eosvibesbloc eosyskoreabp
keoskorea111 philippinebp teamgreymass
We get a lot of information returned to us about the account; anyone can query any account as long as you know the account name. None of the information presented poses a security risk; it is all 'public domain' information about what your account holds.
You can also return the data in a JSON format which is very useful for coders. All you need to do is add -j or --json to the end of the command like so:
cleos -u https://api.eosnewyork.io:443 get account gm2diobtgmge -j
Of course, there is a lot more you can do with cleos that query accounts, but this should give you enough information to start playing. Here is a list of the other keywords with the syntax you can send I got by using the -h or --help
---
Options:
-h,--help Print this help message and exit
-u,--url TEXT=http://localhost:8888/
the http/https URL where nodeos is running
--wallet-url TEXT=http://localhost:8900/
the http/https URL where keosd is running
-r,--header pass specific HTTP header; repeat this option to pass multiple headers
-n,--no-verify don't verify peer certificate when using HTTPS
-v,--verbose output verbose actions on error
--print-request print HTTP request to STDERR
--print-response print HTTP response to STDERR
Subcommands:
version Retrieve version information
create Create various items, on and off the blockchain
get Retrieve various items and information from the blockchain
set Set or update blockchain state
transfer Transfer EOS from account to account
net Interact with local p2p network connections
wallet Interact with local wallet
sign Sign a transaction
push Push arbitrary transactions to the blockchain
multisig Multisig contract commands
system Send eosio.system contract action to the blockchain.