btc-cli

A command-line client for Bitcoin Core's JSON-RPC interface, built against a local Regtest node running in Polar.

Overview

btc-cli talks to a Bitcoin Core node over JSON-RPC and exposes both a set of typed, purpose-built commands (blockchain-info, wallet-info, balance, new-address) and a generic passthrough command (rpc <method> [params...]) for calling any RPC method Bitcoin Core supports.

Credentials and connection details are never hard-coded. They're supplied via flags or environment variables, so pointing the tool at a different node or wallet never requires touching the source.

Architecture

src/
├── main.rs           entry point: parses args, builds the client, dispatches, prints errors
├── cli.rs            clap argument/subcommand definitions
├── config.rs         turns raw CLI/env input into a validated RpcConfig
├── error.rs           AppError enum — every failure mode the app can hit
├── rpc.rs             the JSON-RPC HTTP client (the one reusable core piece)
└── commands/
    ├── mod.rs         dispatch helpers + the generic `rpc` command
    ├── blockchain.rs  blockchain-info
    ├── wallet.rs      wallet-info, balance
    └── address.rs     new-address

Design note: Bitcoin Core exposes wallet-specific RPCs (getbalance, getnewaddress, ...) through a /wallet/<name> endpoint, while node-level RPCs (getblockchaininfo) work on the base URL. /wallet/<name> actually accepts both kinds of calls, so RpcClient routes every request through it whenever a wallet is configured — one code path instead of two.

Installing Polar

1. Docker is required first. On Linux this means Docker Engine (Docker Desktop isn't supported on Linux by Polar).
2. Download Polar for your OS from the GitHub releases page (.deb, AppImage, or RPM on Linux; .dmg on Mac; .exe on Windows). On Linux the direct link for the current version is https://github.com/jamaljsr/polar/releases/download/v4.0.0/polar-linux-amd64-v4.0.0.deb — check the releases page for the exact filename if a newer version has shipped, since asset names aren't consistent between releases.
3. Install it (e.g. on Debian/Ubuntu: sudo apt install ./polar_*.deb).

Creating a Regtest node

1. Launch Polar and click Create Network.
2. Set Bitcoin Core = 1 (leaving a default Lightning node in the designer is fine — it isn't used by this project).
3. Click Start. The first start pulls Docker images for the node software, which can take a few minutes depending on your connection.
4. Click the Bitcoin Core node, open the Actions tab, and mine ~101 blocks. Regtest coinbase rewards need 100 confirmations before they're spendable, so this is what funds the default wallet.

Getting your RPC credentials

Click the Bitcoin Core node in Polar and open the Connect tab. It shows the RPC host/port, username, and password to use below.

Configuring the application

All three of these can be set as flags or as environment variables (flags win if both are given):

Flag	Environment variable	Required
--rpc-url	BITCOIN_RPC_URL	yes
--rpc-user	BITCOIN_RPC_USER	yes
--rpc-password	BITCOIN_RPC_PASSWORD	yes
--wallet	BITCOIN_RPC_WALLET	no*

* Required for wallet-info, balance, and new-address unless Bitcoin Core has exactly one wallet loaded, in which case it's used implicitly.

Example:

export BITCOIN_RPC_URL=http://127.0.0.1:18443
export BITCOIN_RPC_USER=polaruser
export BITCOIN_RPC_PASSWORD=polarpass
export BITCOIN_RPC_WALLET=""   # Polar's default wallet is usually unnamed ("")

Running the application

cargo build
cargo run -- blockchain-info
cargo run -- wallet-info
cargo run -- balance
cargo run -- new-address
cargo run -- rpc getblockcount
cargo run -- rpc getblockhash 200
cargo run -- rpc getblock <hash>

Example output

$ cargo run -- rpc getblockhash 720 
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running `target/debug/btc-cli rpc getblockhash 720`
"25b1bc03fc608391cf85e752946ea842600ede4482a9686a70ce064fb8d6b67c"

Assumptions and design decisions

• Params to the generic rpc command are parsed as JSON when possible (200 → number, true → bool), falling back to a plain string otherwise — the same convention bitcoin-cli itself uses. This matters for things like block hashes, which look numeric but must stay strings.
• Typed structs (BlockchainInfo, WalletInfo) only model the fields this CLI actually displays. serde ignores unrecognized JSON fields by default, so Bitcoin Core adding fields to its responses in future versions won't break deserialization.
• TLS is available via rustls-tls (pure Rust, no OpenSSL system dependency) since Polar's RPC endpoint is plain HTTP on localhost, but the dependency is there in case anyone points this at a TLS-terminated endpoint.
• wallet-info gets its balance figures from getbalances rather than getwalletinfo. Bitcoin Core deprecated getwalletinfo's balance/ unconfirmed_balance fields in 0.19 and fully removed them in a change that shipped in Core v30 (what Polar currently bundles) — getbalances is the documented replacement, and it's also what bitcoin-cli -getinfo itself switched to internally for the same reason.