@getalby/cli 0.2.4 → 0.4.0

package/README.md

@@ -6,17 +6,64 @@ Built for agents - use with the [Alby Bitcoin Payments CLI Skill](https://github
 
 ## Usage
 
+### First-time setup
+
+The CLI is an interface to a wallet and therefore needs a connection secret.
+
+**Option 1: `auth` — for wallets that support it (e.g. Alby Hub)**
+
 ```bash
-# Pass a file path to a connection secret (preferred)
-npx @getalby/cli -c /path/to/secret.txt <command> [options]
+# Step 1: generate a connection URL and open it in your wallet to approve
+# --app-name is the name of the agent/app that will use the wallet via the CLI (e.g. "Claude Code", "OpenClaw")
+npx @getalby/cli auth https://my.albyhub.com --app-name "Claude Code"
 
-# Or pass connection string directly
-npx @getalby/cli -c "nostr+walletconnect://..." <command> [options]
+# Step 2: after approving in the wallet, complete the connection
+npx @getalby/cli auth --complete
+```
+
+**Option 2: `connect` — paste a NWC connection secret directly**
+
+```bash
+npx @getalby/cli connect "nostr+walletconnect://..."
+```
+
+### Multiple wallets
+
+Use `--wallet-name` when setting up to save named connections:
+
+```bash
+npx @getalby/cli connect "nostr+walletconnect://..." --wallet-name work
+npx @getalby/cli auth https://my.albyhub.com --app-name "Claude Code" --wallet-name personal
+```
+
+Then pass `--wallet-name` to any command to use that wallet:
+
+```bash
+npx @getalby/cli --wallet-name work get-balance
+npx @getalby/cli --wallet-name personal pay-invoice --invoice lnbc...
+```
+
+### Connection secret resolution (in order of priority)
+
+1. `--connection-secret` flag (value or path to file)
+2. `--wallet-name` flag (`~/.alby-cli/connection-secret-<name>.key`)
+3. `NWC_URL` environment variable
+4. `~/.alby-cli/connection-secret.key` (default file location)
+
+```bash
+# Use the default saved wallet connection (preferred)
+npx @getalby/cli <command> [options]
+
+# Use a named wallet
+npx @getalby/cli --wallet-name alice <command> [options]
+
+# Or pass a connection secret directly
+npx @getalby/cli -c /path/to/secret.txt <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)).
 
-You can also pass a connection string via the `NWC_URL` environment variable instead of using the `-c` option:
+You can also set the `NWC_URL` environment variable instead of using the `-c` option:
 
 ```txt
 NWC_URL="nostr+walletconnect://..."
@@ -42,44 +89,50 @@ curl -X POST "https://faucet.nwc.dev/wallets/<username>/topup?amount=5000"
 
 ### Wallet Commands
 
-These commands require `--connection-secret`:
+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 L402-protected resource
-npx @getalby/cli -c "nostr+walletconnect://..." fetch-l402 --url "https://example.com/api"
+# 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 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
@@ -88,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
@@ -120,46 +173,7 @@ npx @getalby/cli request-invoice-from-lightning-address --address "hello@getalby
 
 ## Command Reference
 
-### Wallet Commands
-
-These require `-c` or `--connection-secret`:
-
-| 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 `-c` or `--connection-secret`:
-
-| 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/auth.js

@@ -0,0 +1,66 @@
+import { NWCClient } from "@getalby/sdk";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getConnectionSecretPath, getPendingConnectionRelayPath, getPendingConnectionSecretPath, handleError, } from "../utils.js";
+import { generateSecretKey, getPublicKey } from "nostr-tools";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+export function registerAuthCommand(program) {
+    program
+        .command("auth <wallet-url>")
+        .description("Securely connect a wallet with human confirmation via the browser\n\n" +
+        "  Step 1: npx @getalby/cli auth https://my.albyhub.com --app-name MyApp\n" +
+        "  Step 2: after human confirmation, run any command to finalize the connection")
+        .option("--app-name <name>", 'Name of the agent or app that will use this wallet (e.g. "Claude Code")')
+        .option("--relay-url <url>", "Relay URL for the pending connection", "wss://relay.getalby.com/v1")
+        .option("--force", "Overwrite existing connection secret")
+        .option("--remove-pending", "Remove a pending connection and start fresh")
+        .action(async (walletUrl, options) => {
+        await handleError(async () => {
+            const walletName = program.opts().walletName;
+            const connectionSecretPath = getConnectionSecretPath(walletName);
+            const pendingSecretPath = getPendingConnectionSecretPath(walletName);
+            const pendingRelayPath = getPendingConnectionRelayPath(walletName);
+            // Remove pending connection
+            if (options.removePending) {
+                if (!existsSync(pendingSecretPath)) {
+                    console.log(`No pending connection found at ${pendingSecretPath}`);
+                }
+                else {
+                    rmSync(pendingSecretPath);
+                    console.log(`Removed pending connection at ${pendingSecretPath}`);
+                }
+                if (existsSync(pendingRelayPath)) {
+                    rmSync(pendingRelayPath);
+                }
+                return;
+            }
+            // Generate auth URL
+            if (!options.appName) {
+                console.error(`Error: No app name provided.\n` +
+                    `Add --app-name <name> to identify the app in the wallet.`);
+                process.exit(1);
+            }
+            if (existsSync(connectionSecretPath) && !options.force) {
+                console.error(`Error: Already connected. Connection secret exists at ${connectionSecretPath}\n` +
+                    `To overwrite, use --force.`);
+                process.exit(1);
+            }
+            const secret = bytesToHex(generateSecretKey());
+            const pubkey = getPublicKey(hexToBytes(secret));
+            const authUrl = NWCClient.getAuthorizationUrl(`${walletUrl}/apps/new`, { name: options.appName }, pubkey).toString();
+            const dir = join(homedir(), ".alby-cli");
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(pendingSecretPath, secret, { mode: 0o600 });
+            writeFileSync(pendingRelayPath, options.relayUrl, { mode: 0o600 });
+            console.log("Click the following URL to approve the connection in your wallet:\n" +
+                authUrl);
+            const retryCmd = walletName
+                ? `npx @getalby/cli get-balance --wallet-name ${walletName}`
+                : `npx @getalby/cli get-balance`;
+            console.log(`\nOnce approved, run any command, e.g.:\n  ${retryCmd}`);
+        });
+    });
+}

package/build/commands/cancel-hold-invoice.js

@@ -7,7 +7,7 @@ export function registerCancelHoldInvoiceCommand(program) {
         .requiredOption("--payment-hash <hex>", "Payment hash (32 bytes hex)")
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await cancelHoldInvoice(client, {
                 payment_hash: options.paymentHash,
             });

package/build/commands/connect.js

@@ -0,0 +1,46 @@
+import { NWCClient } from "@getalby/sdk";
+import { existsSync } from "node:fs";
+import { getConnectionSecretPath, handleError, saveConnectionSecret, testAndLogConnection, } from "../utils.js";
+export function registerConnectCommand(program) {
+    program
+        .command('connect "[connection-secret]"')
+        .description("Connect to a Nostr Wallet Connect wallet")
+        .option("--force", "Overwrite existing connection secret")
+        .action(async (connectionSecret, options) => {
+        await handleError(async () => {
+            const connectionSecretPath = getConnectionSecretPath(program.opts().walletName);
+            if (existsSync(connectionSecretPath) && !options.force) {
+                console.error(`Error: Already connected. Connection secret exists at ${connectionSecretPath}\n` +
+                    `To overwrite, use --force.`);
+                process.exit(1);
+            }
+            if (!connectionSecret) {
+                console.error(`Usage: npx @getalby/cli connect "<connection-secret>"\n` +
+                    `Provide a NWC connection secret (nostr+walletconnect://...)`);
+                process.exit(1);
+            }
+            if (!connectionSecret.startsWith("nostr+walletconnect://")) {
+                console.error(`Error: Invalid connection secret. Expected format: nostr+walletconnect://...`);
+                process.exit(1);
+            }
+            const client = new NWCClient({
+                nostrWalletConnectUrl: connectionSecret,
+            });
+            if (!client.secret || !/^[0-9a-f]{64}$/i.test(client.secret)) {
+                console.error(`Error: Invalid connection secret. Missing or invalid secret key.`);
+                process.exit(1);
+            }
+            if (!client.walletPubkey ||
+                !/^[0-9a-f]{64}$/i.test(client.walletPubkey)) {
+                console.error(`Error: Invalid connection secret. Missing or invalid wallet pubkey.`);
+                process.exit(1);
+            }
+            if (!client.relayUrls?.length) {
+                console.error(`Error: Invalid connection secret. Missing relay URL.`);
+                process.exit(1);
+            }
+            await testAndLogConnection(client);
+            saveConnectionSecret(connectionSecretPath, connectionSecret, program.opts().verbose);
+        });
+    });
+}

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 = getClient(program);
-            const result = await fetchL402(client, {
+            const client = await getClient(program);
+            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/commands/get-balance.js

@@ -6,7 +6,7 @@ export function registerGetBalanceCommand(program) {
         .description("Get wallet balance")
         .action(async () => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await getBalance(client);
             output(result);
         });

package/build/commands/get-budget.js

@@ -6,7 +6,7 @@ export function registerGetBudgetCommand(program) {
         .description("Get wallet budget information")
         .action(async () => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await getBudget(client);
             output(result);
         });

package/build/commands/get-info.js

@@ -6,7 +6,7 @@ export function registerGetInfoCommand(program) {
         .description("Get wallet info")
         .action(async () => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await getInfo(client);
             output(result);
         });

package/build/commands/get-wallet-service-info.js

@@ -6,7 +6,7 @@ export function registerGetWalletServiceInfoCommand(program) {
         .description("Get wallet service capabilities")
         .action(async () => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await getWalletServiceInfo(client);
             output(result);
         });

package/build/commands/list-transactions.js

@@ -12,7 +12,7 @@ export function registerListTransactionsCommand(program) {
         .option("-t, --type <type>", "Filter by type (incoming|outgoing)")
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await listTransactions(client, {
                 from: options.from,
                 until: options.until,

package/build/commands/lookup-invoice.js

@@ -12,7 +12,7 @@ export function registerLookupInvoiceCommand(program) {
                 console.error("Error: --payment-hash or --invoice is required");
                 process.exit(1);
             }
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await lookupInvoice(client, {
                 payment_hash: options.paymentHash,
                 invoice: options.invoice,

package/build/commands/make-hold-invoice.js

@@ -10,7 +10,7 @@ export function registerMakeHoldInvoiceCommand(program) {
         .option("-e, --expiry <seconds>", "Expiry time in seconds", parseInt)
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await makeHoldInvoice(client, {
                 amount_in_sats: options.amount,
                 payment_hash: options.paymentHash,

package/build/commands/make-invoice.js

@@ -9,7 +9,7 @@ export function registerMakeInvoiceCommand(program) {
         .option("-e, --expiry <seconds>", "Expiry time in seconds", parseInt)
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await makeInvoice(client, {
                 amount_in_sats: options.amount,
                 description: options.description,

package/build/commands/pay-invoice.js

@@ -8,7 +8,7 @@ export function registerPayInvoiceCommand(program) {
         .option("-a, --amount <sats>", "Amount (for zero-amount invoices)", parseInt)
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await payInvoice(client, {
                 invoice: options.invoice,
                 amount_in_sats: options.amount,

package/build/commands/pay-keysend.js

@@ -10,7 +10,7 @@ export function registerPayKeysendCommand(program) {
         .option("--tlv-records <json>", "TLV records as JSON array [{type, value}]")
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             let tlvRecords;
             if (options.tlvRecords) {
                 tlvRecords = JSON.parse(options.tlvRecords);

package/build/commands/settle-hold-invoice.js

@@ -7,7 +7,7 @@ export function registerSettleHoldInvoiceCommand(program) {
         .requiredOption("--preimage <hex>", "Preimage (32 bytes hex)")
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await settleHoldInvoice(client, {
                 preimage: options.preimage,
             });

package/build/commands/sign-message.js

@@ -7,7 +7,7 @@ export function registerSignMessageCommand(program) {
         .requiredOption("-m, --message <text>", "Message to sign")
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await signMessage(client, {
                 message: options.message,
             });

package/build/commands/wait-for-payment.js

@@ -9,7 +9,7 @@ export function registerWaitForPaymentCommand(program) {
         .option("--timeout <seconds>", "Timeout in seconds", parseInt)
         .action(async (options) => {
         await handleError(async () => {
-            const client = getClient(program);
+            const client = await getClient(program);
             const result = await waitForPayment(client, {
                 payment_hash: options.paymentHash,
                 type: options.type,

package/build/index.js

@@ -19,38 +19,64 @@ 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("alby-cli")
-    .description("CLI for Nostr Wallet Connect (NIP-47) with lightning tools")
-    .version("0.2.4")
+    .name("@getalby/cli")
+    .description("CLI for Nostr Wallet Connect (NIP-47) with lightning tools\n\n" +
+    "  Examples:\n" +
+    '    $ npx @getalby/cli connect "nostr+walletconnect://..."\n' +
+    "    $ npx @getalby/cli get-balance\n" +
+    "    $ npx @getalby/cli pay-invoice --invoice lnbc...")
+    .version("0.4.0")
     .option("-c, --connection-secret <string>", "NWC connection secret (nostr+walletconnect://...) or path to file containing it (preferred)")
-    .addHelpText("afterAll", `
+    .option("-w, --wallet-name <name>", "Use a named wallet's connection secret (~/.alby-cli/connection-secret-<name>.key)")
+    .option("-v, --verbose", "Print status messages to stderr")
+    .addHelpText("after", `
+Connection Secret Resolution (in order of priority):
+  1. --connection-secret flag (value or path to file)
+  2. --wallet-name flag (~/.alby-cli/connection-secret-<name>.key)
+  3. NWC_URL environment variable
+  4. ~/.alby-cli/connection-secret.key (default file location)
+
 Security:
   - Do NOT print the connection secret to any logs or otherwise reveal it.
+  - NEVER read the connection secret file (~/.alby-cli/connection-secret.key) directly.
   - NEVER share connection secrets with anyone.
   - 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 all commands
+// Register common wallet commands
+program.commandsGroup("Wallet Commands (require --connection-secret):");
 registerGetBalanceCommand(program);
 registerGetBudgetCommand(program);
 registerGetInfoCommand(program);
-registerGetWalletServiceInfoCommand(program);
 registerMakeInvoiceCommand(program);
-registerMakeHoldInvoiceCommand(program);
-registerSettleHoldInvoiceCommand(program);
-registerCancelHoldInvoiceCommand(program);
 registerPayInvoiceCommand(program);
-registerPayKeysendCommand(program);
 registerLookupInvoiceCommand(program);
 registerListTransactionsCommand(program);
+// Register advanced wallet commands
+program.commandsGroup("Advanced Wallet Commands (require --connection-secret):");
+registerPayKeysendCommand(program);
+registerGetWalletServiceInfoCommand(program);
 registerWaitForPaymentCommand(program);
 registerSignMessageCommand(program);
+registerMakeHoldInvoiceCommand(program);
+registerSettleHoldInvoiceCommand(program);
+registerCancelHoldInvoiceCommand(program);
+// Register lightning tool commands
+program.commandsGroup("Lightning Tools (no --connection-secret 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 (require --connection-secret):");
+registerFetch402Command(program);
+// Register setup commands
+program.commandsGroup("Setup:");
+registerAuthCommand(program);
+registerConnectCommand(program);
 program.parse();

package/build/test/connection-secret.test.js

@@ -45,9 +45,12 @@ describe("Connection Secret Handling", () => {
         expect(result.output.error).toContain("Invalid connection secret");
     });
     test("errors when no connection secret provided", () => {
-        const result = runCli("get-balance");
+        const result = runCli("get-balance", {
+            HOME: "/nonexistent-test-home",
+            NWC_URL: "",
+        });
         expect(result.success).toBe(false);
-        expect(result.output.error).toContain("--connection-secret is required");
+        expect(result.output.error).toContain("No connection secret provided");
     });
     test("errors when connection string is malformed", () => {
         const result = runCli(`-c "nostr+walletconnect://asdf" get-balance`);

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/build/utils.js

@@ -1,30 +1,119 @@
-import { NWCClient } from "@getalby/sdk";
-import { readFileSync } from "node:fs";
+import { NWAClient, NWCClient } from "@getalby/sdk";
+import { getInfo } from "./tools/nwc/get_info.js";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-export function getClient(program) {
+function sanitizeWalletName(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+export function getConnectionSecretPath(name) {
+    const filename = name
+        ? `connection-secret-${sanitizeWalletName(name)}.key`
+        : "connection-secret.key";
+    return join(homedir(), ".alby-cli", filename);
+}
+export function getPendingConnectionSecretPath(name) {
+    const filename = name
+        ? `pending-connection-secret-${sanitizeWalletName(name)}.key`
+        : "pending-connection-secret.key";
+    return join(homedir(), ".alby-cli", filename);
+}
+export function getPendingConnectionRelayPath(name) {
+    const filename = name
+        ? `pending-connection-relay-${sanitizeWalletName(name)}.txt`
+        : "pending-connection-relay.txt";
+    return join(homedir(), ".alby-cli", filename);
+}
+export function saveConnectionSecret(path, secret, verbose) {
+    const alreadyExists = existsSync(path);
+    const dir = join(homedir(), ".alby-cli");
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, secret, { mode: 0o600 });
+    if (alreadyExists) {
+        chmodSync(path, 0o600);
+    }
+    if (verbose) {
+        console.error(`Connection saved to ${path}`);
+    }
+}
+export async function testAndLogConnection(client) {
+    console.log("Testing connection...");
+    const info = await getInfo(client);
+    console.log(`Connected to ${info.alias || "wallet"} (${info.network || "unknown network"})`);
+}
+export async function completePendingConnection(pendingSecretPath, connectionSecretPath, relayUrl, verbose, pendingRelayPath) {
+    const secret = readFileSync(pendingSecretPath, "utf-8").trim();
+    const DEFAULT_RELAY = "wss://relay.getalby.com/v1";
+    if (!relayUrl && pendingRelayPath && existsSync(pendingRelayPath)) {
+        relayUrl = readFileSync(pendingRelayPath, "utf-8").trim();
+    }
+    const resolvedRelay = relayUrl ?? DEFAULT_RELAY;
+    const nwaClient = new NWAClient({
+        appSecretKey: secret,
+        relayUrls: [resolvedRelay],
+        requestMethods: [],
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            unsub?.();
+            reject(new Error("Timed out waiting for wallet approval.\n\nTo retry, run the command again.\nTo cancel: npx @getalby/cli auth --remove-pending"));
+        }, 5000);
+        let unsub;
+        nwaClient
+            .subscribe({
+            onSuccess: async (nwcClient) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                unsub?.();
+                saveConnectionSecret(connectionSecretPath, nwcClient.getNostrWalletConnectUrl(), verbose);
+                rmSync(pendingSecretPath);
+                if (pendingRelayPath && existsSync(pendingRelayPath)) {
+                    rmSync(pendingRelayPath);
+                }
+                resolve(nwcClient);
+            },
+        })
+            .then(({ unsub: u }) => {
+            unsub = u;
+        });
+    });
+}
+export async function getClient(program) {
     const opts = program.opts();
     let connectionSecret = opts.connectionSecret;
-    // Check environment variables if --connection-secret not provided
-    if (!connectionSecret) {
+    const walletName = opts.walletName;
+    const connectionPath = getConnectionSecretPath(walletName);
+    const pendingPath = getPendingConnectionSecretPath(walletName);
+    if (!connectionSecret && !walletName) {
         connectionSecret = process.env.NWC_URL;
     }
     if (!connectionSecret) {
-        const defaultPath = join(homedir(), ".alby-cli", "connection-secret.key");
         try {
-            connectionSecret = readFileSync(defaultPath, "utf-8").trim();
+            connectionSecret = readFileSync(connectionPath, "utf-8").trim();
         }
         catch (error) {
             const err = error;
-            if (err.code !== "ENOENT") {
-                // only throw an error if it's not a file not found error
+            if (err.code !== "ENOENT")
                 throw err;
-            }
         }
     }
+    if (!connectionSecret && existsSync(pendingPath)) {
+        if (opts.verbose) {
+            console.error("Pending connection found. Waiting for wallet approval...");
+        }
+        const pendingRelayPath = getPendingConnectionRelayPath(walletName);
+        return await completePendingConnection(pendingPath, connectionPath, undefined, opts.verbose, pendingRelayPath);
+    }
     if (!connectionSecret) {
-        console.error("Error: No connection secret found. Pass -c <secret>, set NWC_URL, or create ~/.alby-cli/connection-secret.key");
-        process.exit(1);
+        throw new Error("No connection secret provided. Pass -c <secret or file path>, set NWC_URL, use --wallet-name <name>, or create ~/.alby-cli/connection-secret.key");
     }
     // Auto-detect: if it doesn't start with the protocol, treat as file path
     if (!connectionSecret.startsWith("nostr+walletconnect://")) {

package/package.json

@@ -2,12 +2,11 @@
   "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.2.4",
+  "version": "0.4.0",
   "type": "module",
   "main": "build/index.js",
   "bin": {
-    "cli": "build/index.js",
-    "alby-cli": "build/index.js"
+    "cli": "build/index.js"
   },
   "files": [
     "build/**/*"
@@ -33,10 +32,15 @@
   ],
   "author": "Alby contributors",
   "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@getalby/lightning-tools": "^7.0.2",
+    "@getalby/lightning-tools": "^8.0.0",
     "@getalby/sdk": "^7.0.0",
-    "commander": "^13.1.0"
+    "@noble/hashes": "^2.0.1",
+    "commander": "^14.0.3",
+    "nostr-tools": "^2.23.3"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",