Alby NWC CLI

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

Built for agents - best used with the Alby Bitcoin Payments CLI Skill

What this CLI can do

Bitcoin lightning wallet operations using Nostr Wallet Connect (NIP-47). Use when the user needs to send/receive bitcoin payments, pay to crypto/stablecoin addresses, check wallet balance, create invoices, convert between fiat and sats, work with lightning addresses, when an HTTP request returns a 402 Payment Required status code and the user wants to pay for and retry the request, or discover paid API services.

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://..."

Already have a connection secret? Pass it per-command with -c <secret-or-file>, or set the NWC_URL environment variable.

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

List the wallets you've configured (names and connection status only, never the secrets):

npx @getalby/cli list-wallets

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

Run npx @getalby/cli help for the full list of commands and their arguments, or npx @getalby/cli help <command> for one command.

Amounts are always given as --amount with --currency and --network; --currency BTC additionally requires --unit sats|BTC.

Output

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