JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 211
  • Score
    100M100P100Q69181F
  • 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]

# Pass a file path to a connection secret
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).

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 (-c, --wallet-name, or NWC_URL):

# Get wallet balance
npx @getalby/cli -c "nostr+walletconnect://..." get-balance

# Get wallet info
npx @getalby/cli -c "nostr+walletconnect://..." get-info

# Get wallet service capabilities
npx @getalby/cli -c "nostr+walletconnect://..." get-wallet-service-info

# Create an invoice
npx @getalby/cli -c "nostr+walletconnect://..." make-invoice --amount 1000 --description "Payment"

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

# 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

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

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

Output

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