@getalby/cli 0.0.1 → 0.2.1

package/README.md

@@ -2,13 +2,25 @@
 
 CLI for Nostr Wallet Connect (NIP-47) with lightning tools.
 
+Built for agents - use with the [Alby Bitcoin Payments CLI Skill](https://github.com/getAlby/alby-cli-skill)
+
 ## 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)).
+
+You can also pass a connection string via the `NWC_URL` environment variable instead of using the `-c` option:
+
+```txt
+NWC_URL="nostr+walletconnect://..."
+```
 
 ## Testing Wallet
 
@@ -110,44 +122,44 @@ npx @getalby/cli request-invoice-from-lightning-address --address "hello@getalby
 
 ### Wallet Commands
 
-These require `--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` |
+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 `--connection-secret`:
+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` |
+| 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` |
+| 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/index.js

@@ -24,8 +24,8 @@ 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.2.1")
+    .option("-c, --connection-secret <string>", "NWC connection secret (nostr+walletconnect://...) or path to file containing it (preferred)");
 // Register all commands
 registerGetBalanceCommand(program);
 registerGetBudgetCommand(program);

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

@@ -0,0 +1,71 @@
+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");
+    });
+    test("reads connection secret from NWC_URL environment variable", () => {
+        const result = runCli("get-balance", { NWC_URL: wallet.nwcUrl });
+        expect(result.success).toBe(true);
+    });
+    test("reads file path from NWC_URL environment variable", () => {
+        const result = runCli("get-balance", { NWC_URL: secretFilePath });
+        expect(result.success).toBe(true);
+    });
+    test("command line argument takes precedence over environment variables", () => {
+        const result = runCli(`-c "${wallet.nwcUrl}" get-balance`, {
+            NWC_URL: "nostr+walletconnect://invalid"
+        });
+        expect(result.success).toBe(true);
+    });
+});

package/build/test/helpers.js

@@ -40,11 +40,12 @@ export async function createTestWallet(retries = 5) {
     }
     throw new Error("Failed to create test wallet");
 }
-export function runCli(args) {
+export function runCli(args, env) {
     try {
         const result = execSync(`node build/index.js ${args}`, {
             encoding: "utf-8",
             cwd: process.cwd(),
+            env: env ? { ...process.env, ...env } : process.env,
         });
         return { success: true, output: JSON.parse(result) };
     }

package/build/utils.js

@@ -1,12 +1,51 @@
 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;
+    // Check environment variables if --connection-secret not provided
+    if (!connectionSecret) {
+        connectionSecret = process.env.NWC_URL;
+    }
     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.1",
+  "version": "0.2.1",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -17,7 +17,7 @@
     "build": "tsc && chmod 755 build/index.js",
     "start": "node build/index.js",
     "dev": "yarn build && node build/index.js",
-    "test": "vitest run",
+    "test": "npm run build && vitest run",
     "test:watch": "vitest"
   },
   "keywords": [

package/build/auth.js

@@ -1,20 +0,0 @@
-function getConnectionSecretFromBearerAuth(authorizationHeader) {
-    const authParts = authorizationHeader?.split(" ");
-    if (authParts?.length !== 2 ||
-        authParts[0] !== "Bearer" ||
-        !authParts[1].startsWith("nostr+walletconnect://")) {
-        return undefined;
-    }
-    return authParts[1];
-}
-function getConnectionSecretFromQueryParam(nwcParam) {
-    if (!nwcParam || !nwcParam.startsWith("nostr+walletconnect://")) {
-        return undefined;
-    }
-    return nwcParam;
-}
-export function getConnectionSecret(authorizationHeader, nwcQueryParam) {
-    // Try query parameter first, then fall back to bearer auth
-    return (getConnectionSecretFromQueryParam(nwcQueryParam) ||
-        getConnectionSecretFromBearerAuth(authorizationHeader));
-}

package/build/mcp_server.js

@@ -1,36 +0,0 @@
-import { webln } from "@getalby/sdk";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { registerGetInfoTool } from "./tools/nwc/get_info.js";
-import { registerGetWalletServiceInfoTool } from "./tools/nwc/get_wallet_service_info.js";
-import { registerLookupInvoiceTool } from "./tools/nwc/lookup_invoice.js";
-import { registerMakeInvoiceTool } from "./tools/nwc/make_invoice.js";
-import { registerPayInvoiceTool } from "./tools/nwc/pay_invoice.js";
-import { registerGetBalanceTool } from "./tools/nwc/get_balance.js";
-import { registerListTransactionsTool } from "./tools/nwc/list_transactions.js";
-import { registerFetchL402Tool } from "./tools/lightning/fetch_l402.js";
-import { registerFiatToSatsTool } from "./tools/lightning/fiat_to_sats.js";
-import { registerParseInvoiceTool } from "./tools/lightning/parse_invoice.js";
-import { registerRequestInvoiceFromLightningAddressTool } from "./tools/lightning/request_invoice.js";
-export function createMCPServer(client) {
-    const server = new McpServer({
-        name: "@getalby/mcp",
-        version: "1.1.0",
-        title: "Alby MCP Server",
-    });
-    // NWC
-    registerGetWalletServiceInfoTool(server, client);
-    registerGetInfoTool(server, client);
-    registerMakeInvoiceTool(server, client);
-    registerPayInvoiceTool(server, client);
-    registerGetBalanceTool(server, client);
-    registerLookupInvoiceTool(server, client);
-    registerListTransactionsTool(server, client);
-    // Lightning tools
-    registerFetchL402Tool(server, new webln.NostrWebLNProvider({
-        client,
-    }));
-    registerFiatToSatsTool(server);
-    registerParseInvoiceTool(server);
-    registerRequestInvoiceFromLightningAddressTool(server);
-    return server;
-}

package/build/sse.js

@@ -1,50 +0,0 @@
-import { nwc } from "@getalby/sdk";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { createMCPServer } from "./mcp_server.js";
-import { getConnectionSecret } from "./auth.js";
-export function addSSEEndpoints(app) {
-    // Store transports for each session type
-    // SSE is deprecated so we do not put much effort in here (e.g. cleaning up unused sessions)
-    const sessions = {};
-    app.get("/sse", async (req, res) => {
-        const nostrWalletConnectUrl = getConnectionSecret(req.header("Authorization"), req.query.nwc);
-        if (!nostrWalletConnectUrl) {
-            res
-                .status(400)
-                .send("Bearer auth with NWC connection secret or nwc query parameter not provided");
-            return;
-        }
-        const client = new nwc.NWCClient({
-            nostrWalletConnectUrl,
-        });
-        const transport = new SSEServerTransport("/messages", res);
-        const server = createMCPServer(client);
-        sessions[transport.sessionId] = {
-            server,
-            transport,
-        };
-        console.info("Created new SSE session", transport.sessionId);
-        if (req.query.sessionId) {
-            console.info("Request provided its own session ID: " + req.query.sessionId);
-            sessions[req.query.sessionId] = {
-                server,
-                transport,
-            };
-        }
-        server.connect(transport);
-    });
-    app.post("/messages", (req, res) => {
-        const sessionId = req.query.sessionId;
-        console.info("SSE messages request", sessionId);
-        const session = sessions[sessionId];
-        if (session) {
-            console.info("Found session for messages request", sessionId);
-            session.transport.handlePostMessage(req, res);
-        }
-        else {
-            res
-                .status(400)
-                .send("No transport found for sessionId: " + req.query.sessionId);
-        }
-    });
-}

package/build/streamable_http.js

@@ -1,49 +0,0 @@
-import { createMCPServer } from "./mcp_server.js";
-import { nwc } from "@getalby/sdk";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { getConnectionSecret } from "./auth.js";
-import { json } from "express";
-export function addStreamableHttpEndpoints(app) {
-    app.post("/mcp", json(), async (req, res) => {
-        // In stateless mode, create a new instance of transport and server for each request
-        // to ensure complete isolation. A single instance would cause request ID collisions
-        // when multiple clients connect concurrently.
-        try {
-            const nostrWalletConnectUrl = getConnectionSecret(req.header("Authorization"), req.query.nwc);
-            if (!nostrWalletConnectUrl) {
-                res
-                    .status(400)
-                    .send("Bearer auth with NWC connection secret or nwc query parameter not provided");
-                return;
-            }
-            const client = new nwc.NWCClient({
-                nostrWalletConnectUrl,
-            });
-            const server = createMCPServer(client);
-            const transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: undefined,
-            });
-            res.on("close", () => {
-                console.log("Request closed");
-                transport.close();
-                server.close();
-                client.close();
-            });
-            await server.connect(transport);
-            await transport.handleRequest(req, res, req.body);
-        }
-        catch (error) {
-            console.error("Error handling MCP request:", error);
-            if (!res.headersSent) {
-                res.status(500).json({
-                    jsonrpc: "2.0",
-                    error: {
-                        code: -32603,
-                        message: "Internal server error",
-                    },
-                    id: null,
-                });
-            }
-        }
-    });
-}

package/build/tools/lightning/schemas/invoice.js

@@ -1,20 +0,0 @@
-import { z } from "zod";
-export const invoiceSchema = {
-    paymentRequest: z.string().describe("The BOLT-11 payment request"),
-    paymentHash: z.string().describe("Payment hash"),
-    preimage: z.string().nullable().describe("Payment preimage if available"),
-    verify: z
-        .string()
-        .nullable()
-        .describe("URL to verify if the email was paid (LNURL-verify)"),
-    amount_in_sats: z.number().describe("Amount in sats"),
-    expiry: z.number().nullish().describe("Expiry time in seconds"),
-    timestamp: z.number().describe("Creation unix timestamp"),
-    createdDate: z.string().describe("Creation date string"),
-    expiryDate: z.string().nullish().describe("Expiry date string"),
-    description: z.string().nullable().describe("Invoice description"),
-    successAction: z
-        .unknown()
-        .nullable()
-        .describe("Success action to initiate after the invoice has been paid"),
-};

package/build/tools/nwc/schemas/transaction.js

@@ -1,26 +0,0 @@
-import { z } from "zod";
-export const transactionSchema = {
-    type: z.enum(["incoming", "outgoing"]).describe("Transaction type"),
-    state: z
-        .enum(["settled", "pending", "failed"])
-        .nullish()
-        .describe("Transaction state"),
-    invoice: z.string().describe("BOLT-11 invoice"),
-    description: z.string().nullish().describe("Invoice description"),
-    description_hash: z.string().nullish().describe("Description hash"),
-    preimage: z.string().nullish().describe("Preimage of settled payment"),
-    payment_hash: z.string().describe("Payment hash"),
-    amount_in_sats: z.number().describe("Amount in sats"),
-    fees_paid_in_sats: z.number().nullish().describe("Fees paid in sats"),
-    settled_at: z.number().nullish().describe("Timestamp, of settled payment"),
-    created_at: z.number().describe("Creation unix timestamp"),
-    expires_at: z.number().nullish().describe("Expiry unix timestamp"), // TODO: remove nullish once Primal supports it
-    settle_deadline: z
-        .number()
-        .nullish()
-        .describe("HOLD invoice settle deadline"),
-    metadata: z
-        .unknown()
-        .nullish()
-        .describe("Additional metadata about the transaction"),
-};