@btcemail/cli

Command-line interface for btc.email - spam-free email powered by Bitcoin Lightning.

Current version: 0.4.0 (December 28, 2025)

Installation

Option 1: Pre-built Binary (Recommended)

Download the latest binary for your platform from GitHub Releases.

macOS (Apple Silicon):

curl -L https://github.com/8bittts/btcemail/releases/latest/download/btcemail-darwin-arm64 -o btcemail
chmod +x btcemail
sudo mv btcemail /usr/local/bin/

macOS (Intel):

curl -L https://github.com/8bittts/btcemail/releases/latest/download/btcemail-darwin-x64 -o btcemail
chmod +x btcemail
sudo mv btcemail /usr/local/bin/

Linux (x64):

curl -L https://github.com/8bittts/btcemail/releases/latest/download/btcemail-linux-x64 -o btcemail
chmod +x btcemail
sudo mv btcemail /usr/local/bin/

Windows: Download btcemail-windows-x64.exe from the releases page and add to your PATH.

Option 2: npm/bun

npm install -g @btcemail/cli

Or with bun:

bun install -g @btcemail/cli

Quick Start

# Log in (opens browser for authentication)
btcemail login

# List your inbox (numbered for quick access)
btcemail list

# Read email by number or ID
btcemail read 3        # Read email #3 from last list
btcemail read abc123   # Read by email ID

Commands

Authentication

# Log in (opens browser for authentication)
btcemail login

# Show current user
btcemail whoami

# Log out
btcemail logout

Email

# List emails (default: inbox, 20 emails)
btcemail list                     # or: btcemail ls

# List with options
btcemail list --folder sent --limit 50 --page 2

# Read email by number (from last list)
btcemail read 3                   # or: btcemail r 3

# Read by email ID
btcemail read abc123def

# Search emails
btcemail search "invoice"         # or: btcemail s "invoice"

# Send an email (with Lightning payment)
btcemail send --to [email protected] --subject "Hello" --body "Message"

# Send with auto-wait for payment
btcemail send --to [email protected] --subject "Hello" --body "Message" --wait

# Send with pre-paid payment hash
btcemail send --to [email protected] --subject "Hello" --body "Message" --payment-hash <preimage>

Inbound (Pending Emails)

Emails from unknown senders require payment before delivery.

# List pending emails awaiting payment
btcemail inbound pending          # or: btcemail inbound p

# List delivered emails (paid by senders)
btcemail inbound delivered        # or: btcemail inbound d

# View pending email details and payment info
btcemail inbound view <email-id>

# Pay for a pending email (after paying the Lightning invoice)
btcemail inbound pay <email-id> --payment-hash <preimage>

Credits

# Show credit balance
btcemail credits balance          # or: btcemail credits bal

# Show transaction history
btcemail credits history

# Purchase credits with Lightning
btcemail credits purchase         # Shows options
btcemail credits purchase --option 1 --wait

Settings

# Show current settings
btcemail settings                 # or: btcemail settings show

# Set email price in sats
btcemail settings pricing 100

# Toggle payment requirement
btcemail settings require-payment on
btcemail settings require-payment off

# Toggle auto-whitelist after payment
btcemail settings auto-whitelist on
btcemail settings auto-whitelist off

# Set custom auto-reply message
btcemail settings auto-reply "Thanks for your email!"
btcemail settings auto-reply --clear   # Reset to default

Whitelist

Manage senders who can email you for free.

# List whitelist entries
btcemail whitelist                # or: btcemail wl

# Add email or domain
btcemail whitelist add [email protected]
btcemail whitelist add @company.com --note "Work contacts"

# Remove entry by ID
btcemail whitelist remove <entry-id>

Blocklist

Manage blocked senders (silently rejected).

# List blocklist entries
btcemail blocklist                # or: btcemail bl

# Add email or domain
btcemail blocklist add [email protected]
btcemail blocklist add @spam.com --reason "Known spam domain"

# Remove entry by ID
btcemail blocklist remove <entry-id>

Network

Switch between testnet and mainnet Lightning networks.

# Show current network mode
btcemail network

# Switch to testnet (fake Bitcoin)
btcemail network testnet

# Switch to mainnet (real Bitcoin)
btcemail network mainnet

Stats

# Show dashboard statistics
btcemail stats

Options Reference

list

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --folder <folder> | -f | Folder (inbox, sent, drafts) | inbox | | --limit <number> | -l | Number of emails to show | 20 | | --page <number> | -p | Page number for pagination | 1 | | --json | | Output as JSON | false |

read

| Option | Description | Default | |--------|-------------|---------| | --json | Output as JSON | false |

Email ID can be a number (from last list) or an actual email ID.

search

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --limit <number> | -l | Number of results | 20 | | --json | | Output as JSON | false |

send

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --to <emails> | -t | Recipient email(s), comma-separated | required | | --subject <text> | -s | Email subject | required | | --body <text> | -b | Email body | required | | --from <email> | -f | From email (@btc.email address) | auto-detected | | --payment-hash <hash> | | Payment preimage for L402 | optional | | --wait | -w | Wait for payment confirmation | false |

credits purchase

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --option <index> | -o | Purchase option index (0-3) | shows options | | --wait | -w | Wait for payment confirmation | false | | --json | | Output as JSON | false |

Features

Number-Based Email Access

After running btcemail list or btcemail search, emails are cached locally. You can then read them by number:

btcemail list       # Shows numbered list
btcemail read 1     # Read first email
btcemail read 5     # Read fifth email

Cache expires after 30 minutes.

Pagination

Navigate through large email lists with pagination:

btcemail list --page 1              # First page
btcemail list --page 2 --limit 50   # Second page, 50 per page

Payment Waiting

Automatically wait for Lightning payments to complete:

btcemail send --to [email protected] --subject "Hello" --body "Hi" --wait
btcemail credits purchase --option 0 --wait

The CLI will display a QR code and wait up to 5 minutes for payment confirmation.

JSON Output

All list commands support JSON output for scripting:

btcemail list --json | jq '.emails[0].subject'
btcemail credits balance --json | jq '.balanceSats'

Authentication Flow

The CLI uses browser-based authentication:

1. Run btcemail login
2. Browser opens to btc.email login page
3. Complete authentication in browser
4. CLI receives credentials automatically

Credentials are stored locally and expire after 24 hours.

Environment Variables

| Variable | Description | |----------|-------------| | BTCEMAIL_API_URL | Override API base URL (for development) |

Development

# Install dependencies
bun install

# Build
bun run build

# Run locally
bun run start

# Watch mode
bun run dev

# Type check
bun run typecheck

Requirements

• Pre-built binary: No runtime required (standalone executable)
• npm/bun install: Node.js 18 or later
• An active btc.email account

License

MIT