Tag Archives: cli

Getting started: bitcoin-cli

This lesson will be valid for both BTC and BCH.

Before reading the rest of it however, you might have to do some work. This lesson assumes that:

  • You know the very basics.
    • (what is a block, what is a hash and how blocks get chained)
  • You have a bitcoin node running.
    • To install a BTC node go to¬†https://bitcoin.org/en/full-node and grab the bitcoin core client. Then start 'bitcoin-qt' to get a bitcoin node with a GUI, or 'bitcoind' for a node running as a deamon.
    • To install a BCH node go to https://www.bitcoincash.org/#nodes and grab the bitcoin abc client. Then start 'bitcoin-qt' to get a bitcoin node with a GUI, or 'bitcoind' for a node running as a deamon.

(Note 1: If you don't have 170 GB of free hard disk space on your PC, you can run the node with the '--prune' option, which tells it to delete the blocks after verifying them. This way a node can take as little space as ~500 MB)

(Note 2: Do not try to run both nodes, unless you know what you are doing. They both use the same port by default.)



Ok. Let's assume that you already have that node running.

Now let's access the bitcoin-cli. I will be using the BCH version (Bitcoin ABC node).

$ bitcoin-cli
Bitcoin ABC RPC client version v0.17.1.0-e1fa952

bitcoin-cli [options] <command> [params] Send command to Bitcoin ABC
bitcoin-cli [options] -named <command> [name=value] ... Send command to Bitcoin ABC (with named arguments)
bitcoin-cli [options] help List commands
bitcoin-cli [options] help <command> Get help for a command


From the Usage section we can see that we can pass commands, call help to get list of commands and get help for a specific command.
Make sure to always read the help for a command that you are interested in.

Now let's see what the commands are:

$ bitcoin-cli help

And here is the output:

== Blockchain ==
getblock "blockhash" ( verbose )
getblockhash height
getblockheader "hash" ( verbose )
getchaintxstats ( nblocks blockhash )
getmempoolancestors txid (verbose)
getmempooldescendants txid (verbose)
getmempoolentry txid
getrawmempool ( verbose )
gettxout "txid" n ( include_mempool )
gettxoutproof ["txid",...] ( blockhash )
preciousblock "blockhash"
verifychain ( checklevel nblocks )
verifytxoutproof "proof"

== Control ==
help ( "command" )

== Generating ==
generate nblocks ( maxtries )
generatetoaddress nblocks address (maxtries)

== Mining ==
getblocktemplate ( TemplateRequest )
getnetworkhashps ( nblocks height )
prioritisetransaction <txid> <priority delta> <fee delta>
submitblock "hexdata" ( "jsonparametersobject" )

== Network ==
addnode "node" "add|remove|onetry"
disconnectnode "[address]" [nodeid]
getaddednodeinfo ( "node" )
setban "subnet" "add|remove" (bantime) (absolute)
setexcessiveblock blockSize
setnetworkactive true|false

== Rawtransactions ==
createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,"data":"hex",...} ( locktime )
decoderawtransaction "hexstring"
decodescript "hexstring"
fundrawtransaction "hexstring" ( options )
getrawtransaction "txid" ( verbose )
sendrawtransaction "hexstring" ( allowhighfees )
signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype )

== Util ==
createmultisig nrequired ["key",...]
estimatefee nblocks
estimatepriority nblocks
estimatesmartfee nblocks
estimatesmartpriority nblocks
signmessagewithprivkey "privkey" "message"
validateaddress "address"
verifymessage "address" "signature" "message"

== Wallet ==
abandontransaction "txid"
addmultisigaddress nrequired ["key",...] ( "account" )
backupwallet "destination"
dumpprivkey "address"
dumpwallet "filename"
encryptwallet "passphrase"
getaccount "address"
getaccountaddress "account"
getaddressesbyaccount "account"
getbalance ( "account" minconf include_watchonly )
getnewaddress ( "account" )
getreceivedbyaccount "account" ( minconf )
getreceivedbyaddress "address" ( minconf )
gettransaction "txid" ( include_watchonly )
importaddress "address" ( "label" rescan p2sh )
importmulti "requests" "options"
importprivkey "bitcoinprivkey" ( "label" ) ( rescan )
importpubkey "pubkey" ( "label" rescan )
importwallet "filename"
keypoolrefill ( newsize )
listaccounts ( minconf include_watchonly)
listreceivedbyaccount ( minconf include_empty include_watchonly)
listreceivedbyaddress ( minconf include_empty include_watchonly)
listsinceblock ( "blockhash" target_confirmations include_watchonly)
listtransactions ( "account" count skip include_watchonly)
listunspent ( minconf maxconf ["addresses",...] [include_unsafe] )
lockunspent unlock ([{"txid":"txid","vout":n},...])
move "fromaccount" "toaccount" amount ( minconf "comment" )
removeprunedfunds "txid"
sendfrom "fromaccount" "toaddress" amount ( minconf "comment" "comment_to" )
sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] )
sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount )
setaccount "address" "account"
settxfee amount
signmessage "address" "message"

There are quite a few things you can do with this client.
You can read blocks and transaction, send money, handle a wallet, or even publish raw transactions, which give you the ability to write custom scripts. Explaining these scripts is outside of the scope of this article, so let's leave it for another time...

For now, let's see how the command help looks like. Let's get more info on the 'submitblock' from the mining category:

$ bitcoin-cli help submitblock

...and the output is:

submitblock "hexdata" ( "jsonparametersobject" )

Attempts to submit new block to network.
The 'jsonparametersobject' parameter is currently ignored.
See https://en.bitcoin.it/wiki/BIP_0022 for full specification.

1. "hexdata" (string, required) the hex-encoded block data to submit
2. "parameters" (string, optional) object of optional parameters
"workid" : "id" (string, optional) if the server provided a workid, it MUST be included with submissions


> bitcoin-cli submitblock "mydata"
> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "submitblock", "params": ["mydata"] }' -H 'content-type: text/plain;'

As you see, the 'bitcoin-cli' program covers pretty much anything you might need to do when integrating Bitcoin in your programs. There are other tools that do the same, of course. There are libraries in almost any language. The bitcoin-cli however comes bundled with the most popular nodes. It can be considered the default client.

Take some time to read about all it can do.

Now try running these commands and analyze each row of the outputs (consider this your homework):

$ bitcoin-cli getinfo
$ bitcoin-cli getblockchaininfo
$ bitcoin-cli getblock 000000001aeae195809d120b5d66a39c83eb48792e068f8ea1fea19d84a4278a

(getblock only works if your node is not --pruned)

$ bitcoin-cli getnetworkinfo
$ bitcoin-cli getchaintips

(You might need to read the help for getchaintips very carefully. It is a bit harder to understand.)

$ bitcoin-cli getmempoolinfo



Remember that many of the settings you see in the outputs of these commands can change. Some of them can be changed by the owner of the node (like which network you use to connect to the other nodes), while others are decided by the network (like the mining difficulty).
Think about these changes. Make sure to understand what they would mean.

Study hard. Bye!