Command Line Interface

Email from your terminal.

No browser. No tracking. No distractions. Just you, your terminal, and your inbox. Install in seconds, master in minutes.

Get Started Command Reference

Get Started in 60 Seconds

Three commands. That is all it takes to start using BTC.email from your terminal.

Install the CLI

Choose your preferred package manager. Both work identically.

npm

npm install -g @btcemail/cli

bun

bun install -g @btcemail/cli

Connect Your Account

This opens your browser for secure authentication. Your credentials stay local.

btcemail login

Start Using Your Inbox

You are ready. Here are the commands you will use most:

btcemail list- View your inbox

btcemail read 1- Read the first email

btcemail send- Send an email

You are all set!

Run btcemail --help anytime to see all available commands.

Why the Terminal?

The terminal is not just for developers. It is the most private, secure, and distraction-free way to communicate.

No Tracking

No cookies, no analytics, no browser fingerprinting. Your email stays private.

No Distractions

No ads, no popups, no notifications. Focus on what matters.

Full Control

See exactly what commands run. Script and automate as you wish.

Command Reference

Complete list of all commands. Click any section to expand.

Authentication

Connect and manage your account.

btcemail login

Opens browser for OAuth authentication

btcemail logout

Clear stored credentials

btcemail whoami

Show current user and @btc.email address

Reading Email

View and search your inbox.

btcemail list

List inbox (alias: ls)

btcemail list --folder sent --limit 50

List sent folder with custom limit

btcemail read 3

Read email #3 from last list (alias: r)

btcemail search "invoice"

Search emails (alias: s)

Sending Email

Compose and send messages.

btcemail send --to user@example.com --subject "Hello" --body "Hi there"

Send email (shows Lightning invoice if recipient requires payment)

btcemail send --to user@example.com ... --wait

Send and wait for payment confirmation (displays QR code)

Recipients are automatically whitelisted so they can reply without paying.

Inbound Email

Manage emails from external senders awaiting payment.

btcemail bin

List pending emails (shortcut for inbound pending)

btcemail inbound pending

List emails awaiting payment (alias: in p)

btcemail inbound accept <id>

Accept email without payment and whitelist sender (alias: in a)

btcemail inbound delivered

List paid and delivered emails (alias: in d)

Credits

Manage your Lightning credits for sending emails.

btcemail credits balance

Check credit balance (alias: bal)

btcemail credits history

View transaction history

btcemail credits purchase --wait

Buy credits with Lightning (alias: buy)

Settings

Configure your account and pricing.

btcemail settings

Show current settings

btcemail settings pricing 500

Set your email price to 500 sats

btcemail settings require-payment off

Disable payment requirement

btcemail whitelist add friend@example.com

Whitelist sender (alias: wl)

btcemail blocklist add spam@example.com

Block sender forever (alias: bl)

Network and Stats

Switch networks and view statistics.

btcemail network

Show current network (testnet or mainnet)

btcemail network testnet

Switch to testnet (fake Bitcoin for testing)

btcemail network mainnet

Switch to mainnet (real Bitcoin)

btcemail stats

Show dashboard statistics

Wallet Management

Manage Bitcoin addresses for receiving payments.

btcemail wallet

List wallet addresses (alias: w)

btcemail wallet add "Main" bc1q...

Add a Bitcoin address with a name

btcemail wallet default <id>

Set default wallet for a network

Quick Reference

Shorthand aliases for power users. Save keystrokes.

ls = list

r = read

s = search

bin = inbound pending

in = inbound

in p = inbound pending

in d = inbound delivered

in a = inbound accept

wl = whitelist

bl = blocklist

bal = credits balance

buy = credits purchase

w = wallet

Go TUI (Visual Interface)

Prefer a visual interface? The Go TUI provides a full terminal UI with tabs, navigation, and real-time updates.

Build from Source

Requires Go 1.21+ installed.

git clone https://github.com/8bittts/btcemail.gitcd btcemail/packages/tuimake build./bin/btcemail

5 Tabs

1Inbox

2Pending

3Compose

4Settings

5Credits

1-5 = switch tabs

j/k = navigate

Enter = select

? = help

q = quit

Glossary

Key terms you will encounter when using BTC.email.

Sats (Satoshis)

The smallest unit of Bitcoin. 1 BTC = 100,000,000 sats. Most BTC.email payments are measured in sats (typically 100-1000 sats per email).

Lightning Network

A layer-2 payment network built on Bitcoin. Enables instant, low-fee transactions perfect for micropayments like email.

Whitelist

Addresses that can email you for free. Add friends, family, and trusted contacts. Recipients you email are automatically whitelisted.

Pending Email

An email from someone not on your whitelist. The sender must pay your set price (in sats) before it reaches your inbox. Use "accept" to let it through for free.

Credits

Pre-paid balance for sending emails to addresses that require payment. Buy credits with Lightning, spend them when sending.

Testnet vs Mainnet

Testnet uses fake Bitcoin for testing. Mainnet uses real Bitcoin. Switch with btcemail network.

Ready to Start?

Get your @btc.email address and start using spam-free email from your terminal.

Get Your Address Learn More

Works in any terminal. Perfect for YEN.chat, macOS Terminal, Linux, Windows, or your favorite shell.