@getalby/cli 0.0.0 → 0.1.0

package/README.md

@@ -5,10 +5,14 @@ CLI for Nostr Wallet Connect (NIP-47) with lightning tools.
 ## Usage
 
 ```bash
-npx @getalby/cli --connection-secret <NWC_CONNECTION_STRING> <command> [options]
+# Pass a file path to a connection secret (preferred)
+npx @getalby/cli -c /path/to/secret.txt <command> [options]
+
+# Or pass connection string directly
+npx @getalby/cli -c "nostr+walletconnect://..." <command> [options]
 ```
 
-The `--connection-secret` (or `-c`) option is required for wallet operations. You can get a connection string from your NWC-compatible wallet (e.g., [Alby](https://getalby.com)).
+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)).
 
 ## Testing Wallet
 
@@ -48,14 +52,41 @@ npx @getalby/cli -c "nostr+walletconnect://..." make-invoice --amount 1000 --des
 # Pay an invoice
 npx @getalby/cli -c "nostr+walletconnect://..." pay-invoice --invoice "lnbc..."
 
+# Send a keysend payment
+npx @getalby/cli -c "nostr+walletconnect://..." pay-keysend --pubkey "02abc..." --amount 100
+
 # Look up an invoice by payment hash
 npx @getalby/cli -c "nostr+walletconnect://..." lookup-invoice --payment-hash "abc123..."
 
 # List transactions
 npx @getalby/cli -c "nostr+walletconnect://..." list-transactions --limit 10
 
+# Get wallet budget
+npx @getalby/cli -c "nostr+walletconnect://..." get-budget
+
+# Sign a message
+npx @getalby/cli -c "nostr+walletconnect://..." sign-message --message "Hello, World!"
+
 # Fetch L402-protected resource
 npx @getalby/cli -c "nostr+walletconnect://..." fetch-l402 --url "https://example.com/api"
+
+# Wait for a payment notification
+npx @getalby/cli -c "nostr+walletconnect://..." wait-for-payment --payment-hash "abc123..."
+```
+
+### HOLD Invoices
+
+HOLD invoices allow you to accept payments conditionally - the payment is held until you settle or cancel it.
+
+```bash
+# Create a HOLD invoice (you provide the payment hash)
+npx @getalby/cli -c "nostr+walletconnect://..." 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..."
+
+# Cancel a HOLD invoice (reject the payment)
+npx @getalby/cli -c "nostr+walletconnect://..." cancel-hold-invoice --payment-hash "abc123..."
 ```
 
 ### Lightning Tools
@@ -66,28 +97,61 @@ These commands don't require a wallet connection:
 # Convert USD to sats
 npx @getalby/cli fiat-to-sats --currency USD --amount 10
 
+# Convert sats to USD
+npx @getalby/cli sats-to-fiat --amount 1000 --currency USD
+
 # Parse a BOLT-11 invoice
 npx @getalby/cli parse-invoice --invoice "lnbc..."
 
+# Verify a preimage against an invoice
+npx @getalby/cli verify-preimage --invoice "lnbc..." --preimage "abc123..."
+
 # Request invoice from lightning address
-npx @getalby/cli request-invoice --address "hello@getalby.com" --amount 1000
+npx @getalby/cli request-invoice-from-lightning-address --address "hello@getalby.com" --amount 1000
 ```
 
 ## Command Reference
 
-| Command | Description | Required Options |
-|---------|-------------|------------------|
-| `get-balance` | Get wallet balance | - |
-| `get-info` | Get wallet info | - |
-| `get-wallet-service-info` | Get wallet capabilities | - |
-| `make-invoice` | Create a lightning invoice | `--amount` |
-| `pay-invoice` | Pay a lightning invoice | `--invoice` |
-| `lookup-invoice` | Look up an invoice | `--payment-hash` or `--invoice` |
-| `list-transactions` | List transactions | - |
-| `fiat-to-sats` | Convert fiat to sats | `--currency`, `--amount` |
-| `parse-invoice` | Parse a BOLT-11 invoice | `--invoice` |
-| `request-invoice` | Request invoice from lightning address | `--address`, `--amount` |
-| `fetch-l402` | Fetch L402-protected resource | `--url` |
+### 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`   |
 
 ## Output
 

package/build/commands/{request-invoice.js → request-invoice-from-lightning-address.js}

@@ -1,15 +1,15 @@
-import { requestInvoice } from "../tools/lightning/request_invoice.js";
+import { requestInvoiceFromLightningAddress } from "../tools/lightning/request_invoice_from_lightning_address.js";
 import { handleError, output } from "../utils.js";
-export function registerRequestInvoiceCommand(program) {
+export function registerRequestInvoiceFromLightningAddressCommand(program) {
     program
-        .command("request-invoice")
-        .description("Request invoice from lightning address")
+        .command("request-invoice-from-lightning-address")
+        .description("Request an invoice from a lightning address")
         .requiredOption("-a, --address <ln-address>", "Lightning address")
         .requiredOption("-s, --amount <sats>", "Amount in sats", parseInt)
         .option("--comment <text>", "Optional comment")
         .action(async (options) => {
         await handleError(async () => {
-            const result = await requestInvoice({
+            const result = await requestInvoiceFromLightningAddress({
                 lightning_address: options.address,
                 amount_in_sats: options.amount,
                 comment: options.comment,

package/build/index.js

@@ -18,14 +18,14 @@ import { registerFiatToSatsCommand } from "./commands/fiat-to-sats.js";
 import { registerSatsToFiatCommand } from "./commands/sats-to-fiat.js";
 import { registerParseInvoiceCommand } from "./commands/parse-invoice.js";
 import { registerVerifyPreimageCommand } from "./commands/verify-preimage.js";
-import { registerRequestInvoiceCommand } from "./commands/request-invoice.js";
+import { registerRequestInvoiceFromLightningAddressCommand } from "./commands/request-invoice-from-lightning-address.js";
 import { registerFetchL402Command } from "./commands/fetch-l402.js";
 const program = new Command();
 program
     .name("alby-cli")
     .description("CLI for Nostr Wallet Connect (NIP-47) with lightning tools")
-    .version("0.0.0")
-    .option("-c, --connection-secret <string>", "NWC connection secret (nostr+walletconnect://...)");
+    .version("0.1.0")
+    .option("-c, --connection-secret <string>", "NWC connection secret (nostr+walletconnect://...) or path to file containing it (preferred)");
 // Register all commands
 registerGetBalanceCommand(program);
 registerGetBudgetCommand(program);
@@ -45,6 +45,6 @@ registerFiatToSatsCommand(program);
 registerSatsToFiatCommand(program);
 registerParseInvoiceCommand(program);
 registerVerifyPreimageCommand(program);
-registerRequestInvoiceCommand(program);
+registerRequestInvoiceFromLightningAddressCommand(program);
 registerFetchL402Command(program);
 program.parse();

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

@@ -0,0 +1,57 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { createTestWallet, runCli } from "./helpers.js";
+import { writeFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+describe("Connection Secret Handling", () => {
+    let wallet;
+    let secretFilePath;
+    let badSecretFilePath;
+    beforeAll(async () => {
+        wallet = await createTestWallet();
+        // Create temp file with valid connection secret
+        secretFilePath = join(tmpdir(), `nwc-test-secret-${Date.now()}.txt`);
+        writeFileSync(secretFilePath, wallet.nwcUrl);
+        // Create temp file with invalid/truncated content
+        badSecretFilePath = join(tmpdir(), `nwc-test-bad-secret-${Date.now()}.txt`);
+        writeFileSync(badSecretFilePath, "nostr+wallet");
+    }, 60000);
+    afterAll(() => {
+        try {
+            unlinkSync(secretFilePath);
+        }
+        catch { }
+        try {
+            unlinkSync(badSecretFilePath);
+        }
+        catch { }
+    });
+    test("accepts connection string directly", () => {
+        const result = runCli(`-c "${wallet.nwcUrl}" get-balance`);
+        expect(result.success).toBe(true);
+    });
+    test("reads connection secret from file", () => {
+        const result = runCli(`-c "${secretFilePath}" get-balance`);
+        expect(result.success).toBe(true);
+    });
+    test("errors when file does not exist", () => {
+        const result = runCli(`-c "/tmp/nonexistent-file-${Date.now()}" get-balance`);
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("Failed to read connection secret file");
+    });
+    test("errors when file contains invalid connection string", () => {
+        const result = runCli(`-c "${badSecretFilePath}" get-balance`);
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("Invalid connection secret");
+    });
+    test("errors when no connection secret provided", () => {
+        const result = runCli("get-balance");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--connection-secret is required");
+    });
+    test("errors when connection string is malformed", () => {
+        const result = runCli(`-c "nostr+walletconnect://asdf" get-balance`);
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("Invalid connection secret");
+    });
+});

package/build/test/lightning-tools.test.js

@@ -28,8 +28,8 @@ describe("Lightning Tools (no wallet required)", () => {
         expect(result.success).toBe(true);
         expect(result.output.valid).toBe(false);
     });
-    test("request-invoice requests invoice from lightning address", async () => {
-        const result = runCli(`request-invoice -a "${exampleLightningAddress}" -s 100`);
+    test("request-invoice-from-lightning-address requests invoice from lightning address", async () => {
+        const result = runCli(`request-invoice-from-lightning-address -a "${exampleLightningAddress}" -s 100`);
         expect(result.success).toBe(true);
         expect(result.output.paymentRequest.toLowerCase()).toMatch(/^lnbc/);
     });

package/build/tools/lightning/{request_invoice.js → request_invoice_from_lightning_address.js}

@@ -1,5 +1,5 @@
 import { LightningAddress } from "@getalby/lightning-tools";
-export async function requestInvoice(params) {
+export async function requestInvoiceFromLightningAddress(params) {
     const ln = new LightningAddress(params.lightning_address);
     await ln.fetch();
     const { satoshi, ...invoice } = await ln.requestInvoice({

package/build/utils.js

@@ -1,12 +1,47 @@
 import { NWCClient } from "@getalby/sdk";
+import { readFileSync } from "node:fs";
 export function getClient(program) {
     const opts = program.opts();
-    const connectionSecret = opts.connectionSecret;
+    let connectionSecret = opts.connectionSecret;
     if (!connectionSecret) {
         console.error("Error: --connection-secret is required for this command");
         process.exit(1);
     }
-    return new NWCClient({ nostrWalletConnectUrl: connectionSecret });
+    // Auto-detect: if it doesn't start with the protocol, treat as file path
+    if (!connectionSecret.startsWith("nostr+walletconnect://")) {
+        try {
+            connectionSecret = readFileSync(connectionSecret, "utf-8").trim();
+        }
+        catch (error) {
+            console.error(`Error: Failed to read connection secret file "${opts.connectionSecret}": ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    }
+    // Validate the connection string format
+    if (!connectionSecret.startsWith("nostr+walletconnect://")) {
+        console.error(`Error: Invalid connection secret. Expected format: nostr+walletconnect://...\n` +
+            `Got: "${connectionSecret.substring(0, 50)}${connectionSecret.length > 50 ? "..." : ""}"\n` +
+            `Hint: Make sure the connection string is complete and not truncated.`);
+        process.exit(1);
+    }
+    const client = new NWCClient({ nostrWalletConnectUrl: connectionSecret });
+    // Validate client properties
+    if (!client.secret || !/^[0-9a-f]{64}$/i.test(client.secret)) {
+        console.error(`Error: Invalid connection secret. Missing or invalid secret key.\n` +
+            `Hint: Make sure the connection string is complete and not truncated.`);
+        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.\n` +
+            `Hint: Make sure the connection string is complete and not truncated.`);
+        process.exit(1);
+    }
+    if (!client.relayUrls) {
+        console.error(`Error: Invalid connection secret. Missing relay URL.\n` +
+            `Hint: Make sure the connection string is complete and not truncated.`);
+        process.exit(1);
+    }
+    return client;
 }
 export function output(data) {
     console.log(JSON.stringify(data, null, 2));

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.0.0",
+  "version": "0.1.0",
   "type": "module",
   "main": "build/index.js",
   "bin": {