bitcoin-tui

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 65 Open GitHub ↗

A terminal UI for bitcoin

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Bitcoin-tui

A terminal UI for a [Bitcoin node](https://github.com/bitcoin/bitcoin) built with [FTXUI](https://github.com/ArthurSonzogni/FTXUI).

Connects to a local or remote Bitcoin Core node via JSON-RPC and displays live blockchain, mempool, network, and peer data — and lets you broadcast transactions directly from the terminal. No external libraries required beyond FTXUI.

## Screenshot

**Dashboard tab:**

**Mempool tab:**

**Block search overlay:**

## Features

- **Dashboard** - blockchain height, difficulty, sync progress, network status, and mempool summary at a glance
- **Mempool** - transaction count, virtual size, total fees, min relay fee, memory usage gauge, and animated recent block fill visualization (newest first, colored green/yellow/orange by weight - blocks slide right when a new block arrives; block age shown per column; number of columns adapts to terminal width)
- **Search** - press `/` to search mempool or confirmed transactions (txid); drill into blocks, inputs, and outputs (`txindex=1` required for confirmed lookups)
- **Network** - connection counts (inbound/outbound), client version, protocol version, relay fee; soft-fork tracking table showing all consensus deployments with status and activation height (`getdeploymentinfo`, loaded on first visit)
- **Peers** - live peer table with address, network type, direction, ping, bytes sent/received, and tip height; navigate with `down/up-arrow` and press `Enter` to open a detail overlay for any peer; disconnect or ban (24h) from the detail overlay; press `[a]` to view/manage added nodes, `[b]` to view/manage the ban list
- **Tools** - broadcast raw transactions via `sendrawtransaction`; live private broadcast queue (Bitcoin Core PR #29415, shown when non-empty); shutdown Bitcoin Core node and exit with `[Q]`

- Background polling thread - non-blocking UI with configurable refresh interval
- No external dependencies beyond FTXUI (JSON parsing and HTTP handled in-tree)

## Requirements

- C++20 compiler (GCC 12+ or Clang 15+)
- CMake 3.22+
- Internet access at configure time (CMake fetches FTXUI v7.0.1 and Catch2 v3.7.1 via FetchContent)
- Bitcoin (Core) node with RPC enabled

## Build

```sh
cmake -B build
cmake --build build -j$(nproc)
```

Binary is output to `build/bin/bitcoin-tui`.

## Tests

```sh
ctest --test-dir build --output-on-failure
```

Tests cover the vendored JSON implementation: parsing, serialization, type queries, accessor methods, error handling, and real Bitcoin Core RPC response shapes.

## Usage

```
bitcoin-tui [options]

Connection:
  -h, --host <host>      RPC host             (default: 127.0.0.1)
  -p, --port <port>      RPC port             (default: 8332)

Settings not given here are read from the node's bitcoin.conf, honouring its
network sections: rpcport, rpcconnect, rpccookiefile, rpcuser/rpcpassword.

Authentication (cookie auth is used by default):
  -c, --cookie <path>    Path to .cookie file (auto-detected if omitted)
  -d, --datadir <path>   Bitcoin data directory for cookie lookup
  -u, --user <user>      RPC username         (disables cookie auth)
  -P, --password <pass>  RPC password         (disables cookie auth)

Network:
      --testnet          Use testnet3 port (18332) and cookie subdir
      --testnet4         Use testnet4 port (48332) and cookie subdir
      --regtest          Use regtest  port (18443) and cookie subdir
      --signet           Use signet   port (38332) and cookie subdir

Node:
      --conf <path>      Node's bitcoin.conf  (default: <datadir>/bitcoin.conf)

Launch:
      --bitcoind <path>  Path to bitcoind binary (default: found via PATH)

Display:
  -r, --refresh <secs>   Refresh interval     (default: 5)
  -v, --version          Print version and exit

```

### Examples

```sh
# Mainnet — auto-detects ~/.bitcoin/.cookie (or ~/Library/Application Support/Bitcoin/.cookie on macOS)
./build/bin/bitcoin-tui

# Testnet — uses testnet3/.cookie automatically
./build/bin/bitcoin-tui --testnet

# Custom data directory
./build/bin/bitcoin-tui --datadir /mnt/bitcoin

# Explicit cookie file
./build/bin/bitcoin-tui --cookie /var/lib/bitcoind/.cookie

# Explicit credentials (rpcuser/rpcpassword style)
./build/bin/bitcoin-tui -u alice -P hunter2

# Remote node with faster refresh
./build/bin/bitcoin-tui --host 192.168.1.10 -u alice -P hunter2 -r 2
```

## Bitcoin Core configuration

Cookie authentication is the default. Just enable the RPC server in `bitcoin.conf`:

```ini
server=1
```

Bitcoin Core writes `.cookie` to the data directory on startup. `bitcoin-tui` reads it automatically — no credentials needed.

For remote access or `rpcuser`/`rpcpassword`-style auth, add:

```ini
server=1
rpcallowip=127.0.0.1
rpcbind=127.0.0.1
rpcuser=alice
rpcpassword=hunter2
```

Then pass `-u alice -P hunter2` on the command line.

## License

MIT

bitcoin-tui

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README