JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 211
  • Score
    100M100P100Q69132F
  • License MIT

CLI for Nostr Wallet Connect (NIP-47) with a few additional useful lightning tools

Package Exports

  • @getalby/cli
  • @getalby/cli/build/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@getalby/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Alby NWC CLI

CLI for Nostr Wallet Connect (NIP-47) with lightning tools.

Built for agents - use with the Alby Bitcoin Payments CLI Skill

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)

# 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"

# Step 2: after approving in the wallet, complete the connection
npx @getalby/cli auth --complete

Option 2: connect — paste a NWC connection secret directly

npx @getalby/cli connect "nostr+walletconnect://..."

Multiple wallets

Use --wallet-name when setting up to save named connections:

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:

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)
# 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).

You can also set the NWC_URL environment variable instead of using the -c option:

NWC_URL="nostr+walletconnect://..."

Testing Wallet

For testing the CLI without using real funds, you can create a test wallet using the NWC Faucet:

curl -X POST "https://faucet.nwc.dev?balance=10000"

This returns a connection string for a test wallet with 10,000 sats. Test wallets can send payments to each other but cannot interact with the real lightning network.

To top up an existing test wallet:

curl -X POST "https://faucet.nwc.dev/wallets/<username>/topup?amount=5000"

Commands

Wallet Commands

These commands require a wallet connection - either default connection, or specify a custom connection with -w, '-c', or NWC_URL environment variable:

# Get wallet balance
npx @getalby/cli get-balance

# Get wallet info
npx @getalby/cli get-info

# Get wallet service capabilities
npx @getalby/cli get-wallet-service-info

# Create an invoice
npx @getalby/cli make-invoice --amount 1000 --description "Payment"

# Pay an invoice
npx @getalby/cli pay-invoice --invoice "lnbc..."

# Send a keysend payment
npx @getalby/cli pay-keysend --pubkey "02abc..." --amount 100

# Look up an invoice by payment hash
npx @getalby/cli lookup-invoice --payment-hash "abc123..."

# List transactions
npx @getalby/cli list-transactions --limit 10

# Get wallet budget
npx @getalby/cli get-budget

# Sign a message
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 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 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.

# Create a HOLD invoice (you provide the payment hash)
npx @getalby/cli make-hold-invoice --amount 1000 --payment-hash "abc123..."

# Settle a HOLD invoice (claim the payment)
npx @getalby/cli settle-hold-invoice --preimage "def456..."

# Cancel a HOLD invoice (reject the payment)
npx @getalby/cli cancel-hold-invoice --payment-hash "abc123..."

Lightning Tools

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-from-lightning-address --address "hello@getalby.com" --amount 1000

Command Reference

Run npx @getalby/cli help for a full list of commands and possible arguments.

Output

All commands output JSON to stdout. Errors are output to stderr as JSON with an error field.