Essential Bitcoin CLI Commands: A Practical Guide

Managing a Bitcoin node requires familiarity with its command-line interface (CLI). This guide covers essential bitcoin-cli commands for wallet management, transaction handling, and network operations, providing a clear reference for node operators.

Specifying a Configuration File

To execute commands with a specific configuration file, use the -conf parameter. This is useful when running multiple nodes or custom setups.

bitcoin-cli -conf=/root/.bitcoin/bitcoin.conf rpc_command

Wallet Management Commands

View Wallet Information

Retrieve comprehensive wallet details, including version, balance, and transaction count.

bitcoin-cli getwalletinfo

Check Balance

Obtain the total spendable balance from all addresses whose private keys are held in the node's wallet.

bitcoin-cli getbalance

Note: This only includes balances from addresses for which the node holds the private key.

Generate a New Address

Create a new Bitcoin address associated with an account label.

bitcoin-cli getnewaddress "account_label"

Encrypt Wallet

Secure your wallet by encrypting it with a passphrase. This must be done before any sensitive operations.

bitcoin-cli encryptwallet your_password

Unlock Wallet

Temporarily unlock an encrypted wallet to perform operations. Specify the duration in seconds.

bitcoin-cli walletpassphrase your_password 300

Backup Wallet

Create a backup of the wallet.dat file to a specified location. The wallet must be unlocked first.

bitcoin-cli backupwallet /path/to/backup.file

Export Private Key

Export the private key for a specific address. Wallet unlocking is required.

bitcoin-cli dumpprivkey "address"

Transaction Commands

Send to Address

Send funds from the default account to a specified address.

bitcoin-cli sendtoaddress "address" amount

Generate Blocks (Testnet/Regtest)

On testnets or private regtest networks, generate new blocks to confirm transactions.

bitcoin-cli generate 1

Note: On regtest, a certain number of blocks (often over 100) must be generated before mature coinbase rewards are spendable.

List Transactions

Retrieve a list of recent transactions involving the node's wallet addresses.

bitcoin-cli listtransactions "*" 10 0 true

Prerequisite: Ensure txindex=1 is set in your bitcoin.conf file.

Get Transaction Details

Fetch detailed information about a specific transaction by its ID (txid).

bitcoin-cli gettransaction "txid"

Note: This command typically only returns full details for transactions involving the node's own wallet addresses.

List Unspent Outputs

View all unspent transaction outputs (UTXOs) available for spending.

bitcoin-cli listunspent

To filter for a specific address and confirmation range:

bitcoin-cli listunspent 0 99999999 '["your_address"]'

Raw Transaction Handling

Create Raw Transaction

Construct an unsigned raw transaction by specifying inputs (UTXOs) and outputs.

bitcoin-cli createrawtransaction '[{"txid":"previous_txid","vout":output_index}]' '{"recipient_address":amount}'

Fund Raw Transaction

Automatically select UTXOs to fund a raw transaction and specify a change address.

bitcoin-cli fundrawtransaction "hex_string" '{"changeAddress":"your_change_address"}'

Sign Raw Transaction

Sign a raw transaction with the necessary private keys.

bitcoin-cli signrawtransactionwithkey "hex_string" '["private_key1", "private_key2"]'

Send Raw Transaction

Broadcast a signed raw transaction to the network.

bitcoin-cli sendrawtransaction "signed_hex_string"

Network and Help Commands

Get Help

Access the general help menu to explore all available commands.

bitcoin-cli help

For a deeper dive into advanced functionalities and specific RPC calls, you can explore more strategies available in the official documentation.

Frequently Asked Questions

What is the difference between getbalance and listunspent?
getbalance returns a single figure representing the total spendable balance. listunspent provides a detailed list of individual unspent transaction outputs (UTXOs), including their value and transaction ID, which is necessary for building raw transactions.

Why does my transaction not appear when I use listtransactions?
The listtransactions command primarily tracks transactions involving addresses for which the node holds the private keys. If you imported an address using importaddress (watch-only), its transactions may appear, but details might be limited. Ensure txindex=1 is configured for full transaction history indexing.

How long should I unlock my wallet for?
Unlock only for the minimum time required to perform your operations (e.g., 30 or 60 seconds) using the walletpassphrase command. This limits the window of vulnerability if your system is compromised. The wallet will automatically relock after the time expires.

Can I use these commands on the mainnet?
Yes, these commands are universal across Bitcoin networks (mainnet, testnet, regtest). Exercise extreme caution when executing commands like sendtoaddress or sendrawtransaction on mainnet, as they involve spending real funds.

What does 'Invalid or non-wallet transaction id' mean?
This error usually occurs when using gettransaction with a TXID that is not related to any address in your node's wallet. Your node only has full knowledge of transactions pertinent to its own managed addresses.

Is it safe to export my private keys?
Exporting private keys exposes them to potential theft. This operation should only be performed on a secure, offline system for the purpose of creating backups. Never expose your private keys to an internet-connected machine.