gistfile1.md

date	section	title
March 2024	1	BITCOIN-CLI

NAME

bitcoin-cli - manual page for bitcoin-cli v26.99.0-0fa9f17332a6-dirty

SYNOPSIS

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

DESCRIPTION

Bitcoin Core RPC client version v26.99.0-0fa9f17332a6-dirty

OPTIONS

-?

Print this help message and exit

-addrinfo

Get the number of addresses known to the node, per network and total, after filtering for quality and recency. The total number of addresses known to the node may be higher.

-color=<when>

Color setting for CLI output (default: auto). Valid values: always, auto (add color codes when standard output is connected to a terminal and OS is not WIN32), never.

-conf=<file>

Specify configuration file. Relative paths will be prefixed by datadir location. (default: bitcoin.conf)

-datadir=<dir>

Specify data directory

-generate

Generate blocks, equivalent to RPC getnewaddress followed by RPC generatetoaddress. Optional positional integer arguments are number of blocks to generate (default: 1) and maximum iterations to try (default: 1000000), equivalent to RPC generatetoaddress nblocks and maxtries arguments. Example: bitcoin-cli -generate 4 1000

-getinfo

Get general information from the remote server. Note that unlike server-side RPC calls, the output of -getinfo is the result of multiple non-atomic requests. Some entries in the output may represent results from different states (e.g. wallet balance may be as of a different block from the chain state reported)

-named

Pass named instead of positional arguments (default: false)

-netinfo

Get network peer connection information from the remote server. An optional integer argument from 0 to 4 can be passed for different peers listings (default: 0). Pass "help" for detailed help documentation.

-rpcclienttimeout=<n>

Timeout in seconds during HTTP requests, or 0 for no timeout. (default: 900)

-rpcconnect=<ip>

Send commands to node running on <ip> (default: 127.0.0.1)

-rpccookiefile=<loc>

Location of the auth cookie. Relative paths will be prefixed by a net-specific datadir location. (default: data dir)

-rpcpassword=<pw>

Password for JSON-RPC connections

-rpcport=<port>

Connect to JSON-RPC on <port> (default: 8332, testnet: 18332, signet: 38332, regtest: 18443)

-rpcuser=<user>

Username for JSON-RPC connections

-rpcwait

Wait for RPC server to start

-rpcwaittimeout=<n>

Timeout in seconds to wait for the RPC server to start, or 0 for no timeout. (default: 0)

-rpcwallet=<walletname>

Send RPC for non-default wallet on RPC server (needs to exactly match corresponding -wallet option passed to bitcoind). This changes the RPC endpoint used, e.g. http://127.0.0.1:8332/wallet/\

-stdin

Read extra arguments from standard input, one per line until EOF/Ctrl-D (recommended for sensitive information such as passphrases). When combined with -stdinrpcpass, the first line from standard input is used for the RPC password.

-stdinrpcpass

Read RPC password from standard input as a single line. When combined with -stdin, the first line from standard input is used for the RPC password. When combined with -stdinwalletpassphrase, -stdinrpcpass consumes the first line, and -stdinwalletpassphrase consumes the second.

-stdinwalletpassphrase

Read wallet passphrase from standard input as a single line. When combined with -stdin, the first line from standard input is used for the wallet passphrase.

-version

Print version and exit

Debugging/Testing options:

Chain selection options:

-chain=<chain>

Use the chain <chain> (default: main). Allowed values: main, test, signet, regtest

-signet

Use the signet chain. Equivalent to -chain=signet. Note that the network is defined by the -signetchallenge parameter

-signetchallenge

Blocks must satisfy the given script to be considered valid (only for signet networks; defaults to the global default signet test network challenge)

-signetseednode

Specify a seed node for the signet network, in the hostname[:port] format, e.g. sig.net:1234 (may be used multiple times to specify multiple seed nodes; defaults to the global default signet test network seed node(s))

-testnet

Use the test chain. Equivalent to -chain=test.

FILES

Data directory

The data directory is the default location where the Bitcoin Core files are stored:

Linux
$HOME/.bitcoin/

macOS
$HOME/Library/Application Support/Bitcoin/

Windows
%APPDATA%\Bitcoin

Chain-specific data directory

All content of the data directory, except for the bitcoin.conf file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ:

Mainnet
*path_to_datadir*/

Testnet
*path_to_datadir*/testnet3

Signet
*path_to_datadir*/signet

Regtest
*path_to_datadir*/regtest

Data directory layout

blocks/
Blocks directory; can be specified by -blocksdir option (except for blocks/index/)

blocks/index/
LevelDB database for block index; -blocksdir option does not affect this path

chainstate/
LevelDB database for blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from)

wallets/
Contains wallets; can be specified by -walletdir option; if wallets/ subdirectory does not exist, wallets reside in the data directory

./anchors.dat
Anchor IP address database, created on shutdown and deleted at startup. Anchors are last known outgoing block-relay-only peers that are tried to reconnect to on startup)

./banlist.json
Stores the addresses/subnets of banned nodes

./bitcoin.conf
User-defined configuration settings for bitcoind or bitcoin-qt. File is not written to by the software and must be created manually. Path can be specified by -conf option

./bitcoind.pid
Stores the process ID (PID) of bitcoind or bitcoin-qt while running; created at start and deleted on shutdown; can be specified by -pid option

./debug.log
Contains debug information and general logging generated by bitcoind or bitcoin-qt; can be specified by -debuglogfile option

./fee_estimates.dat
Stores statistics used to estimate minimum transaction fees required for confirmation

./mempool.dat
Dump of the mempool's transactions

./onion_v3_private_key
Cached Tor onion service private key for -listenonion option

./i2p_private_key
Private key that corresponds to our I2P address. When -i2psam= is specified the contents of this file is used to identify ourselves for making outgoing connections to I2P peers and possibly accepting incoming ones. Automatically generated if it does not exist.

./peers.dat
Peer IP address database (custom format)

./settings.json
Read-write settings set through GUI or RPC interfaces, augmenting manual settings from bitcoin.conf. File is created automatically if read-write settings storage is not disabled with -nosettings option. Path can be specified with -settings option.

./.cookie
Session RPC authentication cookie

Berkeley DB database based wallets

database/
BDB logging files. Part of BDB environment; created at start and deleted on shutdown; a user *must keep it as safe* as personal wallet wallet.dat

./db.log
BDB error file

./wallet.dat
Personal wallet (a BDB database) with keys and transactions

./walletlock
BDB wallet lock file

SQLite database based wallets

./wallet.dat
Personal wallet (a SQLite database) with keys and transactions

./wallet.dat-journal
SQLite Rollback Journal file for wallet.dat. Usually created at start and deleted on shutdown. A user *must keep it as safe* as the wallet.dat file.

GUI settings

bitcoin-qt uses QSettings, this implies platform-specific locations where application settings are stored. Check https://doc.qt.io/qt-5/qsettings.html#locations-where-application-settings-are-stored

COPYRIGHT

Copyright (C) 2009-2024 The Bitcoin Core developers

Please contribute if you find Bitcoin Core useful. Visit <https://bitcoincore.org/> for further information about the software. The source code is available from <https://github.com/bitcoin/bitcoin>.

This is experimental software. Distributed under the MIT software license, see the accompanying file COPYING or <https://opensource.org/licenses/MIT>

SEE ALSO

bitcoind(1), bitcoin-tx(1), bitcoin-wallet(1), bitcoin-util(1), bitcoin-qt(1)