| name | alby-hub |
| description | Manage a self-custodial Alby Hub lightning node via @getalby/hub-cli — setup, authentication, channels, LSP, backups, lightning and on-chain payments, swaps, creating budgeted, scoped NWC app connections that give agents and apps controlled, revocable access to the wallet, and managing sub-wallets (isolated balances with their own lightning address, plus transfers between them). |
| license | Apache-2.0 |
| metadata | {"author":"getAlby","version":"0.2.2"} |
Alby Hub Agent Skill
Experimental / incomplete: The hub CLI does not cover every Alby Hub feature. If a user asks for something in the unsupported features list, direct them to use the Alby Hub web interface instead.
When to use this skill
Use this skill to manage an Alby Hub lightning node via the CLI.
Hub management vs. payments. This skill is optimized for managing the hub — setup, channels, LSP, NWC app creation, backups. A core hub strength is minting multiple budgeted, scoped NWC connections — one per app or purpose — so the user stays in control and each connection's blast radius is small. Once an NWC connection exists (via create-app), the alby-bitcoin-payments skill is the better fit for using it — budgeted payments, 402 paid APIs, HOLD invoices, keysend, lightning address lookups, and fiat/sats conversion.
- Installation: How to get Alby Hub running — Linux, Docker, Raspberry Pi, desktop
- Overview: What Alby Hub is and how the CLI fits in
- Backends: LDK, LND, Phoenixd, Cashu, Bark — features and configuration
- Bark (Ark): Setup, env-var config, and limitations of the Ark-based backend
- Initial Setup: First-time hub initialisation flow
- Post-Setup Checklist: Things a new user should do AFTER initial setup — surface on first setup or when asked "what's next?"
- Authentication: Token management, start, unlock, token priority
- Hub Management: Stop, health, info, node status
- Alby Account: Connect, check (get-alby-account), and link your account — lightning address, automatic encrypted backups & email notifications, connect/link/get-alby-account/get-alby-status commands
- Alby Pro: Paid subscription benefits
- Backups: Static channel backups, recovery phrase backup
- LSP: Order a channel up front — channel suggestions, channel offer (use on LND/CLN, or for advance liquidity or a specific channel size)
- JIT Channels: Default first-receive flow on LDK — a channel opens just-in-time on the first payment, fee deducted from it (LDK only)
- Channels: Open/close channels, peers, connect-peer, node connection info
- Payments: Pay/make invoices, transactions, lookup, balances, wallet address
- Swaps: Swap on-chain bitcoin ↔ lightning (swap in / swap out), powered by boltz.exchange — confirm amounts and addresses before swapping
- Apps: NWC app management — create-app, list apps
- Sub-wallets: First-class isolated wallets — create-sub-wallet, transfer funds in/out, lightning addresses, pay from a sub-wallet
- QR Codes: Display invoices and NWC connection strings as QR codes using qrencode
- Custom Node Commands: Backend-specific node commands
- Mutinynet: Signet testing setup without real bitcoin
Key Rules
Running the CLI
npx -y @getalby/hub-cli [options] <command>
Default Hub URL
The CLI connects to http://localhost:8029 by default. Override with -u <url> or the HUB_URL environment variable.
Default Backend
LDK is the default backend. Omit --backend when using LDK. Only specify --backend for non-LDK backends (LND, Phoenixd, Cashu, Bark).
Token Priority
Tokens are resolved in this order (highest to lowest priority):
-t, --token <jwt> flagHUB_TOKEN environment variable~/.hub-cli/token.jwt (default saved token)
Always use --save with start or unlock. Without it the token is ephemeral and lost when the shell exits.
AUTO_UNLOCK_PASSWORD
When the hub is configured with the AUTO_UNLOCK_PASSWORD environment variable, it starts the lightning node automatically on launch. In this case, skip start and call unlock directly to obtain a token.
Output Format
All commands output JSON to stdout. Errors are written to stderr as JSON with a message field.
Language Conventions
Use lowercase for "bitcoin" and "lightning" unless they appear as the first word in a sentence.
User Communication
Do NOT give users CLI commands to run unless one of these two conditions applies:
- The task requires input the agent cannot provide (e.g. a password) — in that case, give the command template with a placeholder like
YOUR_PASSWORD and explain what the user should do.
- The user explicitly asks for the CLI command.
For all other follow-up checking or monitoring, use plain language. For example: "If you'd like to check whether your channel is ready to use, just ask."
Security
Connection secrets (NWC)
create-app returns a nostrWalletConnectUrl. It grants wallet access within the app's scopes and budget.
- The connection secret is for the user who requested the app — hand it to them directly (a QR code is preferred; see QR Codes).
- DO NOT print the connection secret to any logs or otherwise reveal it outside of that direct handover.
- NEVER share a connection secret, or any part of it (pubkey, secret, relay, etc.), with any third party, external service, or other chat — every part can be used to gain wallet access or reduce wallet privacy.
See Apps.
Token files
The JWT at ~/.hub-cli/token.jwt grants full hub API access until it expires.
- DO NOT read the token file. Check for its existence only if you need to.
- Prefer the saved token or
HUB_TOKEN env var over -t eyJ... inline — command-line tokens leak into shell history.
- Do not dump the environment (
env, printenv) in a way that exposes HUB_TOKEN in the conversation.
See Authentication.
Recovery phrase & hub backups
- The agent MUST NOT read
.recovery files or encrypted hub backups. Tell the user the file path so they can store it offline.
See Backups.
Passwords
For commands that need a password, the user can give their hub unlock password to you directly but you should note that this is insecure. You can also provide commands for them to run manually (but requires more technical knowledge and is not always possible depending on the interface).
