@btcemail/cli 0.1.1 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 Command-line interface for btc.email - spam-free email powered by Bitcoin Lightning.
 
+Current version: 0.4.0 (December 28, 2025)
+
 ## Installation
 
 ```bash
@@ -14,10 +16,18 @@ Or with bun:
 bun install -g @btcemail/cli
 ```
 
-## Usage
+## Quick Start
 
 ```bash
-btcemail [command] [options]
+# 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
@@ -39,24 +49,27 @@ btcemail logout
 
 ```bash
 # List emails (default: inbox, 20 emails)
-btcemail list
+btcemail list                     # or: btcemail ls
 
 # List with options
-btcemail list --folder sent --limit 50
+btcemail list --folder sent --limit 50 --page 2
+
+# Read email by number (from last list)
+btcemail read 3                   # or: btcemail r 3
 
-# Output as JSON
-btcemail list --json
+# Read by email ID
+btcemail read abc123def
 
-# Read a specific email
-btcemail read <email-id>
+# Search emails
+btcemail search "invoice"         # or: btcemail s "invoice"
 
-# Read as JSON
-btcemail read <email-id> --json
+# Send an email (with Lightning payment)
+btcemail send --to recipient@example.com --subject "Hello" --body "Message"
 
-# Send an email (L402 payment required for external recipients)
-btcemail send --to recipient@example.com --subject "Hello" --body "Message body"
+# Send with auto-wait for payment
+btcemail send --to recipient@example.com --subject "Hello" --body "Message" --wait
 
-# Send with payment (after paying Lightning invoice)
+# Send with pre-paid payment hash
 btcemail send --to recipient@example.com --subject "Hello" --body "Message" --payment-hash <preimage>
 ```
 
@@ -66,7 +79,10 @@ Emails from unknown senders require payment before delivery.
 
 ```bash
 # List pending emails awaiting payment
-btcemail inbound pending
+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>
@@ -79,18 +95,102 @@ btcemail inbound pay <email-id> --payment-hash <preimage>
 
 ```bash
 # Show credit balance
-btcemail credits 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
+
+```bash
+# 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.
+
+```bash
+# List whitelist entries
+btcemail whitelist                # or: btcemail wl
+
+# Add email or domain
+btcemail whitelist add friend@example.com
+btcemail whitelist add @company.com --note "Work contacts"
+
+# Remove entry by ID
+btcemail whitelist remove <entry-id>
+```
+
+### Blocklist
+
+Manage blocked senders (silently rejected).
+
+```bash
+# List blocklist entries
+btcemail blocklist                # or: btcemail bl
+
+# Add email or domain
+btcemail blocklist add spammer@example.com
+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.
+
+```bash
+# Show current network mode
+btcemail network
+
+# Switch to testnet (fake Bitcoin)
+btcemail network testnet
+
+# Switch to mainnet (real Bitcoin)
+btcemail network mainnet
 ```
 
-## Options
+### Stats
+
+```bash
+# Show dashboard statistics
+btcemail stats
+```
+
+## Options Reference
 
 ### list
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-f, --folder <folder>` | Folder to list (inbox, sent, drafts) | inbox |
-| `-l, --limit <number>` | Number of emails to show | 20 |
-| `--json` | Output as JSON | false |
+| 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
 
@@ -98,34 +198,76 @@ btcemail credits balance
 |--------|-------------|---------|
 | `--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 | Description | Default |
-|--------|-------------|---------|
-| `-t, --to <emails>` | Recipient email(s), comma-separated | required |
-| `-s, --subject <text>` | Email subject | required |
-| `-b, --body <text>` | Email body | required |
-| `-f, --from <email>` | From email (@btc.email address) | auto-detected |
-| `--payment-hash <hash>` | Payment preimage for L402 | optional |
+| 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 |
 
-### inbound pending
+### credits purchase
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-l, --limit <number>` | Number of emails to show | 20 |
-| `--json` | Output as JSON | false |
+| 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 |
 
-### inbound view
+## Features
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--json` | Output as JSON | false |
+### Number-Based Email Access
 
-### inbound pay
+After running `btcemail list` or `btcemail search`, emails are cached locally. You can then read them by number:
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--payment-hash <hash>` | Payment preimage from Lightning invoice | required |
+```bash
+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:
+
+```bash
+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:
+
+```bash
+btcemail send --to bob@example.com --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:
+
+```bash
+btcemail list --json | jq '.emails[0].subject'
+btcemail credits balance --json | jq '.balanceSats'
+```
 
 ## Authentication Flow
 
@@ -158,6 +300,9 @@ bun run start
 
 # Watch mode
 bun run dev
+
+# Type check
+bun run typecheck
 ```
 
 ## Requirements