@btcemail/cli 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +110 -41
  2. package/dist/index.js +737 -113
  3. package/dist/index.js.map +1 -1
  4. package/package.json +4 -2
package/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  Command-line interface for btc.email - spam-free email powered by Bitcoin Lightning.
4
4
 
5
+ Current version: 0.3.0 (December 28, 2025)
6
+
5
7
  ## Installation
6
8
 
7
9
  ```bash
@@ -14,10 +16,18 @@ Or with bun:
14
16
  bun install -g @btcemail/cli
15
17
  ```
16
18
 
17
- ## Usage
19
+ ## Quick Start
18
20
 
19
21
  ```bash
20
- btcemail [command] [options]
22
+ # Log in (opens browser for authentication)
23
+ btcemail login
24
+
25
+ # List your inbox (numbered for quick access)
26
+ btcemail list
27
+
28
+ # Read email by number or ID
29
+ btcemail read 3 # Read email #3 from last list
30
+ btcemail read abc123 # Read by email ID
21
31
  ```
22
32
 
23
33
  ## Commands
@@ -39,24 +49,27 @@ btcemail logout
39
49
 
40
50
  ```bash
41
51
  # List emails (default: inbox, 20 emails)
42
- btcemail list
52
+ btcemail list # or: btcemail ls
43
53
 
44
54
  # List with options
45
- btcemail list --folder sent --limit 50
55
+ btcemail list --folder sent --limit 50 --page 2
56
+
57
+ # Read email by number (from last list)
58
+ btcemail read 3 # or: btcemail r 3
46
59
 
47
- # Output as JSON
48
- btcemail list --json
60
+ # Read by email ID
61
+ btcemail read abc123def
49
62
 
50
- # Read a specific email
51
- btcemail read <email-id>
63
+ # Search emails
64
+ btcemail search "invoice" # or: btcemail s "invoice"
52
65
 
53
- # Read as JSON
54
- btcemail read <email-id> --json
66
+ # Send an email (with Lightning payment)
67
+ btcemail send --to recipient@example.com --subject "Hello" --body "Message"
55
68
 
56
- # Send an email (L402 payment required for external recipients)
57
- btcemail send --to recipient@example.com --subject "Hello" --body "Message body"
69
+ # Send with auto-wait for payment
70
+ btcemail send --to recipient@example.com --subject "Hello" --body "Message" --wait
58
71
 
59
- # Send with payment (after paying Lightning invoice)
72
+ # Send with pre-paid payment hash
60
73
  btcemail send --to recipient@example.com --subject "Hello" --body "Message" --payment-hash <preimage>
61
74
  ```
62
75
 
@@ -66,7 +79,10 @@ Emails from unknown senders require payment before delivery.
66
79
 
67
80
  ```bash
68
81
  # List pending emails awaiting payment
69
- btcemail inbound pending
82
+ btcemail inbound pending # or: btcemail inbound p
83
+
84
+ # List delivered emails (paid by senders)
85
+ btcemail inbound delivered # or: btcemail inbound d
70
86
 
71
87
  # View pending email details and payment info
72
88
  btcemail inbound view <email-id>
@@ -79,18 +95,26 @@ btcemail inbound pay <email-id> --payment-hash <preimage>
79
95
 
80
96
  ```bash
81
97
  # Show credit balance
82
- btcemail credits balance
98
+ btcemail credits balance # or: btcemail credits bal
99
+
100
+ # Show transaction history
101
+ btcemail credits history
102
+
103
+ # Purchase credits with Lightning
104
+ btcemail credits purchase # Shows options
105
+ btcemail credits purchase --option 1 --wait
83
106
  ```
84
107
 
85
- ## Options
108
+ ## Options Reference
86
109
 
87
110
  ### list
88
111
 
89
- | Option | Description | Default |
90
- |--------|-------------|---------|
91
- | `-f, --folder <folder>` | Folder to list (inbox, sent, drafts) | inbox |
92
- | `-l, --limit <number>` | Number of emails to show | 20 |
93
- | `--json` | Output as JSON | false |
112
+ | Option | Alias | Description | Default |
113
+ |--------|-------|-------------|---------|
114
+ | `--folder <folder>` | `-f` | Folder (inbox, sent, drafts) | inbox |
115
+ | `--limit <number>` | `-l` | Number of emails to show | 20 |
116
+ | `--page <number>` | `-p` | Page number for pagination | 1 |
117
+ | `--json` | | Output as JSON | false |
94
118
 
95
119
  ### read
96
120
 
@@ -98,34 +122,76 @@ btcemail credits balance
98
122
  |--------|-------------|---------|
99
123
  | `--json` | Output as JSON | false |
100
124
 
125
+ Email ID can be a number (from last list) or an actual email ID.
126
+
127
+ ### search
128
+
129
+ | Option | Alias | Description | Default |
130
+ |--------|-------|-------------|---------|
131
+ | `--limit <number>` | `-l` | Number of results | 20 |
132
+ | `--json` | | Output as JSON | false |
133
+
101
134
  ### send
102
135
 
103
- | Option | Description | Default |
104
- |--------|-------------|---------|
105
- | `-t, --to <emails>` | Recipient email(s), comma-separated | required |
106
- | `-s, --subject <text>` | Email subject | required |
107
- | `-b, --body <text>` | Email body | required |
108
- | `-f, --from <email>` | From email (@btc.email address) | auto-detected |
109
- | `--payment-hash <hash>` | Payment preimage for L402 | optional |
136
+ | Option | Alias | Description | Default |
137
+ |--------|-------|-------------|---------|
138
+ | `--to <emails>` | `-t` | Recipient email(s), comma-separated | required |
139
+ | `--subject <text>` | `-s` | Email subject | required |
140
+ | `--body <text>` | `-b` | Email body | required |
141
+ | `--from <email>` | `-f` | From email (@btc.email address) | auto-detected |
142
+ | `--payment-hash <hash>` | | Payment preimage for L402 | optional |
143
+ | `--wait` | `-w` | Wait for payment confirmation | false |
110
144
 
111
- ### inbound pending
145
+ ### credits purchase
112
146
 
113
- | Option | Description | Default |
114
- |--------|-------------|---------|
115
- | `-l, --limit <number>` | Number of emails to show | 20 |
116
- | `--json` | Output as JSON | false |
147
+ | Option | Alias | Description | Default |
148
+ |--------|-------|-------------|---------|
149
+ | `--option <index>` | `-o` | Purchase option index (0-3) | shows options |
150
+ | `--wait` | `-w` | Wait for payment confirmation | false |
151
+ | `--json` | | Output as JSON | false |
117
152
 
118
- ### inbound view
153
+ ## Features
119
154
 
120
- | Option | Description | Default |
121
- |--------|-------------|---------|
122
- | `--json` | Output as JSON | false |
155
+ ### Number-Based Email Access
123
156
 
124
- ### inbound pay
157
+ After running `btcemail list` or `btcemail search`, emails are cached locally. You can then read them by number:
125
158
 
126
- | Option | Description | Default |
127
- |--------|-------------|---------|
128
- | `--payment-hash <hash>` | Payment preimage from Lightning invoice | required |
159
+ ```bash
160
+ btcemail list # Shows numbered list
161
+ btcemail read 1 # Read first email
162
+ btcemail read 5 # Read fifth email
163
+ ```
164
+
165
+ Cache expires after 30 minutes.
166
+
167
+ ### Pagination
168
+
169
+ Navigate through large email lists with pagination:
170
+
171
+ ```bash
172
+ btcemail list --page 1 # First page
173
+ btcemail list --page 2 --limit 50 # Second page, 50 per page
174
+ ```
175
+
176
+ ### Payment Waiting
177
+
178
+ Automatically wait for Lightning payments to complete:
179
+
180
+ ```bash
181
+ btcemail send --to bob@example.com --subject "Hello" --body "Hi" --wait
182
+ btcemail credits purchase --option 0 --wait
183
+ ```
184
+
185
+ The CLI will display a QR code and wait up to 5 minutes for payment confirmation.
186
+
187
+ ### JSON Output
188
+
189
+ All list commands support JSON output for scripting:
190
+
191
+ ```bash
192
+ btcemail list --json | jq '.emails[0].subject'
193
+ btcemail credits balance --json | jq '.balanceSats'
194
+ ```
129
195
 
130
196
  ## Authentication Flow
131
197
 
@@ -158,6 +224,9 @@ bun run start
158
224
 
159
225
  # Watch mode
160
226
  bun run dev
227
+
228
+ # Type check
229
+ bun run typecheck
161
230
  ```
162
231
 
163
232
  ## Requirements