@getalby/cli 0.3.0 → 0.4.1

package/README.md

@@ -57,11 +57,8 @@ npx @getalby/cli <command> [options]
 # Use a named wallet
 npx @getalby/cli --wallet-name alice <command> [options]
 
-# Pass a file path to a connection secret
+# Or pass a connection secret directly
 npx @getalby/cli -c /path/to/secret.txt <command> [options]
-
-# Or pass connection string directly
-npx @getalby/cli -c "nostr+walletconnect://..." <command> [options]
 ```
 
 The `-c` option auto-detects whether you're passing a connection string or a file path. You can get a connection string from your NWC-compatible wallet (e.g., [Alby](https://getalby.com)).
@@ -92,44 +89,50 @@ curl -X POST "https://faucet.nwc.dev/wallets/<username>/topup?amount=5000"
 
 ### Wallet Commands
 
-These commands require a wallet connection (`-c`, `--wallet-name`, or `NWC_URL`):
+These commands require a wallet connection - either default connection, or specify a custom connection with `-w`, '-c', or `NWC_URL` environment variable:
 
 ```bash
 # Get wallet balance
-npx @getalby/cli -c "nostr+walletconnect://..." get-balance
+npx @getalby/cli get-balance
 
 # Get wallet info
-npx @getalby/cli -c "nostr+walletconnect://..." get-info
+npx @getalby/cli get-info
 
 # Get wallet service capabilities
-npx @getalby/cli -c "nostr+walletconnect://..." get-wallet-service-info
+npx @getalby/cli get-wallet-service-info
 
 # Create an invoice
-npx @getalby/cli -c "nostr+walletconnect://..." make-invoice --amount 1000 --description "Payment"
+npx @getalby/cli make-invoice --amount 1000 --description "Payment"
 
 # Pay an invoice
-npx @getalby/cli -c "nostr+walletconnect://..." pay-invoice --invoice "lnbc..."
+npx @getalby/cli pay-invoice --invoice "lnbc..."
 
 # Send a keysend payment
-npx @getalby/cli -c "nostr+walletconnect://..." pay-keysend --pubkey "02abc..." --amount 100
+npx @getalby/cli pay-keysend --pubkey "02abc..." --amount 100
 
 # Look up an invoice by payment hash
-npx @getalby/cli -c "nostr+walletconnect://..." lookup-invoice --payment-hash "abc123..."
+npx @getalby/cli lookup-invoice --payment-hash "abc123..."
 
 # List transactions
-npx @getalby/cli -c "nostr+walletconnect://..." list-transactions --limit 10
+npx @getalby/cli list-transactions --limit 10
 
 # Get wallet budget
-npx @getalby/cli -c "nostr+walletconnect://..." get-budget
+npx @getalby/cli get-budget
 
 # Sign a message
-npx @getalby/cli -c "nostr+walletconnect://..." sign-message --message "Hello, World!"
+npx @getalby/cli sign-message --message "Hello, World!"
+
+# Fetch a payment-protected resource (auto-detects L402, X402, MPP)
+npx @getalby/cli fetch --url "https://example.com/api"
+
+# Fetch with custom method, headers, and body
+npx @getalby/cli fetch --url "https://example.com/api" --method POST --body '{"query":"hello"}' --headers '{"Accept":"application/json"}'
 
-# Fetch L402-protected resource
-npx @getalby/cli -c "nostr+walletconnect://..." fetch-l402 --url "https://example.com/api"
+# Fetch with a custom max amount (default: 5000 sats, 0 = no limit)
+npx @getalby/cli fetch --url "https://example.com/api" --max-amount 1000
 
 # Wait for a payment notification
-npx @getalby/cli -c "nostr+walletconnect://..." wait-for-payment --payment-hash "abc123..."
+npx @getalby/cli wait-for-payment --payment-hash "abc123..."
 ```
 
 ### HOLD Invoices
@@ -138,13 +141,13 @@ HOLD invoices allow you to accept payments conditionally - the payment is held u
 
 ```bash
 # Create a HOLD invoice (you provide the payment hash)
-npx @getalby/cli -c "nostr+walletconnect://..." make-hold-invoice --amount 1000 --payment-hash "abc123..."
+npx @getalby/cli make-hold-invoice --amount 1000 --payment-hash "abc123..."
 
 # Settle a HOLD invoice (claim the payment)
-npx @getalby/cli -c "nostr+walletconnect://..." settle-hold-invoice --preimage "def456..."
+npx @getalby/cli settle-hold-invoice --preimage "def456..."
 
 # Cancel a HOLD invoice (reject the payment)
-npx @getalby/cli -c "nostr+walletconnect://..." cancel-hold-invoice --payment-hash "abc123..."
+npx @getalby/cli cancel-hold-invoice --payment-hash "abc123..."
 ```
 
 ### Lightning Tools
@@ -170,46 +173,7 @@ npx @getalby/cli request-invoice-from-lightning-address --address "hello@getalby
 
 ## Command Reference
 
-### Wallet Commands
-
-These require a wallet connection (`-c`, `--wallet-name`, or `NWC_URL`):
-
-| Command                   | Description                    | Required Options                |
-| ------------------------- | ------------------------------ | ------------------------------- |
-| `get-balance`             | Get wallet balance             | -                               |
-| `get-info`                | Get wallet info                | -                               |
-| `get-wallet-service-info` | Get wallet capabilities        | -                               |
-| `get-budget`              | Get wallet budget              | -                               |
-| `make-invoice`            | Create a lightning invoice     | `--amount`                      |
-| `pay-invoice`             | Pay a lightning invoice        | `--invoice`                     |
-| `pay-keysend`             | Send a keysend payment         | `--pubkey`, `--amount`          |
-| `lookup-invoice`          | Look up an invoice             | `--payment-hash` or `--invoice` |
-| `list-transactions`       | List transactions              | -                               |
-| `sign-message`            | Sign a message with wallet key | `--message`                     |
-| `wait-for-payment`        | Wait for payment notification  | `--payment-hash`                |
-| `fetch-l402`              | Fetch L402-protected resource  | `--url`                         |
-
-### HOLD Invoice Commands
-
-These require a wallet connection (`-c`, `--wallet-name`, or `NWC_URL`):
-
-| Command               | Description           | Required Options             |
-| --------------------- | --------------------- | ---------------------------- |
-| `make-hold-invoice`   | Create a HOLD invoice | `--amount`, `--payment-hash` |
-| `settle-hold-invoice` | Settle a HOLD invoice | `--preimage`                 |
-| `cancel-hold-invoice` | Cancel a HOLD invoice | `--payment-hash`             |
-
-### Lightning Tools
-
-These don't require a wallet connection:
-
-| Command                                  | Description                            | Required Options          |
-| ---------------------------------------- | -------------------------------------- | ------------------------- |
-| `fiat-to-sats`                           | Convert fiat to sats                   | `--currency`, `--amount`  |
-| `sats-to-fiat`                           | Convert sats to fiat                   | `--amount`, `--currency`  |
-| `parse-invoice`                          | Parse a BOLT-11 invoice                | `--invoice`               |
-| `verify-preimage`                        | Verify preimage against invoice        | `--invoice`, `--preimage` |
-| `request-invoice-from-lightning-address` | Request invoice from lightning address | `--address`, `--amount`   |
+Run `npx @getalby/cli help` for a full list of commands and possible arguments.
 
 ## Output
 

package/build/commands/{fetch-l402.js → fetch.js}

@@ -1,21 +1,23 @@
-import { fetchL402 } from "../tools/lightning/fetch_l402.js";
+import { fetch402 } from "../tools/lightning/fetch.js";
 import { getClient, handleError, output } from "../utils.js";
-export function registerFetchL402Command(program) {
+export function registerFetch402Command(program) {
     program
-        .command("fetch-l402")
-        .description("Fetch L402-protected resource")
+        .command("fetch")
+        .description("Fetch a payment-protected resource (auto-detects L402, X402, MPP)")
         .requiredOption("-u, --url <url>", "URL to fetch")
         .option("-m, --method <method>", "HTTP method (GET, POST, etc.)")
         .option("-b, --body <json>", "Request body (JSON string)")
         .option("-H, --headers <json>", "Additional headers (JSON string)")
+        .option("--max-amount <sats>", "Maximum amount in sats to pay per request. Aborts if the endpoint requests more. (default: 5000, 0 = no limit)", parseInt)
         .action(async (options) => {
         await handleError(async () => {
             const client = await getClient(program);
-            const result = await fetchL402(client, {
+            const result = await fetch402(client, {
                 url: options.url,
                 method: options.method,
                 body: options.body,
                 headers: options.headers ? JSON.parse(options.headers) : undefined,
+                maxAmountSats: options.maxAmount,
             });
             output(result);
         });

package/build/index.js

@@ -19,20 +19,22 @@ import { registerSatsToFiatCommand } from "./commands/sats-to-fiat.js";
 import { registerParseInvoiceCommand } from "./commands/parse-invoice.js";
 import { registerVerifyPreimageCommand } from "./commands/verify-preimage.js";
 import { registerRequestInvoiceFromLightningAddressCommand } from "./commands/request-invoice-from-lightning-address.js";
-import { registerFetchL402Command } from "./commands/fetch-l402.js";
+import { registerFetch402Command } from "./commands/fetch.js";
 import { registerConnectCommand } from "./commands/connect.js";
 import { registerAuthCommand } from "./commands/auth.js";
 const program = new Command();
 program
     .name("@getalby/cli")
-    .description("CLI for Nostr Wallet Connect (NIP-47) with lightning tools\n\n" +
+    .description("CLI for Nostr Wallet Connect (NIP-47) with lightning tools\n" +
+    "  Run 'auth' or 'connect' first to set up a wallet connection.\n\n" +
     "  Examples:\n" +
+    "    $ npx @getalby/cli auth https://my.albyhub.com --app-name OpenClaw\n" +
     '    $ npx @getalby/cli connect "nostr+walletconnect://..."\n' +
     "    $ npx @getalby/cli get-balance\n" +
     "    $ npx @getalby/cli pay-invoice --invoice lnbc...")
-    .version("0.3.0")
-    .option("-c, --connection-secret <string>", "NWC connection secret (nostr+walletconnect://...) or path to file containing it (preferred)")
+    .version("0.4.1")
     .option("-w, --wallet-name <name>", "Use a named wallet's connection secret (~/.alby-cli/connection-secret-<name>.key)")
+    .option("-c, --connection-secret <string>", "NWC connection secret (nostr+walletconnect://...) or path to file containing it (preferred)")
     .option("-v, --verbose", "Print status messages to stderr")
     .addHelpText("after", `
 Connection Secret Resolution (in order of priority):
@@ -48,7 +50,7 @@ Security:
   - NEVER share any part of a connection secret (pubkey, secret, relay etc.) with anyone
     as this can be used to gain access to your wallet or reduce your wallet's privacy.`);
 // Register common wallet commands
-program.commandsGroup("Wallet Commands (require --connection-secret):");
+program.commandsGroup("Wallet Commands (requires wallet connection):");
 registerGetBalanceCommand(program);
 registerGetBudgetCommand(program);
 registerGetInfoCommand(program);
@@ -57,7 +59,7 @@ registerPayInvoiceCommand(program);
 registerLookupInvoiceCommand(program);
 registerListTransactionsCommand(program);
 // Register advanced wallet commands
-program.commandsGroup("Advanced Wallet Commands (require --connection-secret):");
+program.commandsGroup("Advanced Wallet Commands (requires wallet connection):");
 registerPayKeysendCommand(program);
 registerGetWalletServiceInfoCommand(program);
 registerWaitForPaymentCommand(program);
@@ -66,13 +68,15 @@ registerMakeHoldInvoiceCommand(program);
 registerSettleHoldInvoiceCommand(program);
 registerCancelHoldInvoiceCommand(program);
 // Register lightning tool commands
-program.commandsGroup("Lightning Tools (no --connection-secret required):");
+program.commandsGroup("Lightning Tools (no wallet connection required):");
 registerFiatToSatsCommand(program);
 registerSatsToFiatCommand(program);
 registerParseInvoiceCommand(program);
 registerVerifyPreimageCommand(program);
 registerRequestInvoiceFromLightningAddressCommand(program);
-registerFetchL402Command(program);
+// Register fetch command for payment-protected resources
+program.commandsGroup("HTTP 402 Payments (requires wallet connection):");
+registerFetch402Command(program);
 // Register setup commands
 program.commandsGroup("Setup:");
 registerAuthCommand(program);

package/build/tools/lightning/{fetch_l402.js → fetch.js}

@@ -1,9 +1,11 @@
-import { fetchWithL402 } from "@getalby/lightning-tools";
-export async function fetchL402(client, params) {
+import { fetch402 as fetch402Lib } from "@getalby/lightning-tools/402";
+const DEFAULT_MAX_AMOUNT_SATS = 5000;
+export async function fetch402(client, params) {
+    const method = params.method?.toUpperCase();
     const requestOptions = {
-        method: params.method,
+        method,
     };
-    if (params.method && params.method !== "GET" && params.method !== "HEAD") {
+    if (method && method !== "GET" && method !== "HEAD") {
         requestOptions.body = params.body;
         requestOptions.headers = {
             "Content-Type": "application/json",
@@ -13,13 +15,10 @@ export async function fetchL402(client, params) {
     else if (params.headers) {
         requestOptions.headers = params.headers;
     }
-    const result = await fetchWithL402(params.url, requestOptions, {
-        wallet: {
-            sendPayment: async (invoice) => {
-                const result = await client.payInvoice({ invoice });
-                return { preimage: result.preimage };
-            },
-        },
+    const maxAmountSats = params.maxAmountSats ?? DEFAULT_MAX_AMOUNT_SATS;
+    const result = await fetch402Lib(params.url, requestOptions, {
+        wallet: client,
+        maxAmount: maxAmountSats || undefined,
     });
     const responseContent = await result.text();
     if (!result.ok) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@getalby/cli",
   "description": "CLI for Nostr Wallet Connect (NIP-47) with a few additional useful lightning tools",
   "repository": "https://github.com/getAlby/cli.git",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -36,7 +36,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@getalby/lightning-tools": "^7.0.2",
+    "@getalby/lightning-tools": "^8.0.0",
     "@getalby/sdk": "^7.0.0",
     "@noble/hashes": "^2.0.1",
     "commander": "^14.0.3",