Nunchuk CLI

A command-line tool that lets AI agents use Bitcoin safely. Agents operate within group wallets and miniscript wallets where user keys retain ultimate control — transactions above policy limits require explicit user approval.

Built for integration with AI agent frameworks. See agent-skills for ready-made skills.

• ✅ Group Wallet (m-of-n multisig)
• 🛠 Miniscript Wallet

Prerequisites

• Node.js >= 18
• Nunchuk API key — generate one at the Developer Portal

Installation

npm install -g nunchuk-cli

Development

git clone [email protected]:nunchuk-io/nunchuk-cli.git
cd nunchuk-cli
npm install
npm run build
npm link  # makes `nunchuk` available globally

Quick Start

# Authenticate
nunchuk auth login

# Set network (mainnet or testnet)
nunchuk network set testnet

# Generate a software signing key
nunchuk key generate --name "Alice"

# Derive signer info for a stored key
nunchuk key info --fingerprint <xfp>

# List stored keys
nunchuk key list

# Authenticate separately on another network when needed
nunchuk --network mainnet auth login
nunchuk --network testnet auth login

# Create a 2-of-3 sandbox (defaults to NATIVE_SEGWIT)
nunchuk sandbox create --name "My Wallet" --m 2 --n 3

# Invite participants by email
nunchuk invitation send <sandbox-id> [email protected] [email protected]

# List your pending invitations
nunchuk invitation list

# Accept or deny an invitation
nunchuk invitation accept <invitation-id>
nunchuk invitation deny <invitation-id>

# Add stored key to sandbox (auto-derives descriptor)
nunchuk sandbox add-key <sandbox-id> --slot 0 --fingerprint <xfp>

# Or provide the full signer descriptor directly
nunchuk sandbox add-key <sandbox-id> --slot 1 \
  --descriptor "[aabbccdd/48h/1h/0h/2h]tpubXXX"

# Or provide xpub + path manually
nunchuk sandbox add-key <sandbox-id> --slot 2 \
  --fingerprint aabbccdd \
  --xpub tpubXXX \
  --path "m/48h/1h/0h/2h"

# Finalize into an active wallet
nunchuk sandbox finalize <sandbox-id>

# View wallets
nunchuk wallet list

# View wallets without Electrum balance lookup
nunchuk wallet list --no-balance

# Get a fresh receive address
nunchuk wallet address get <wallet-id>

# Export wallet descriptor and BSMS for backup/recovery
nunchuk wallet export <wallet-id>

# Rename a wallet
nunchuk wallet rename <wallet-id> --name "New Name"

# Recover a wallet from backup
nunchuk wallet recover --file wallet-backup.txt

# Send bitcoin
nunchuk tx create --wallet <wallet-id> --to <address> --amount 100000
nunchuk tx sign --wallet <wallet-id> --tx-id <tx-id>
nunchuk tx sign --wallet <wallet-id> --tx-id <tx-id> --psbt <signed-psbt>
nunchuk tx broadcast --wallet <wallet-id> --tx-id <tx-id>

# View transaction history
nunchuk tx list --wallet <wallet-id>

# Enable platform key (auto-signing by Nunchuk backend)
nunchuk sandbox platform-key enable <sandbox-id>

# Set global policy with spending limit
nunchuk sandbox platform-key set-policy <sandbox-id> \
  --auto-broadcast --limit-amount 1000 --limit-currency USD --limit-interval DAILY

# Set per-signer policy
nunchuk sandbox platform-key set-policy <sandbox-id> \
  --signer <xfp> --auto-broadcast --signing-delay 1h

# Set policy via JSON (supports spendingLimit per signer)
nunchuk sandbox platform-key set-policy <sandbox-id> --policy-json '{
  "signers": [
    {
      "masterFingerprint": "534a4a82",
      "autoBroadcastTransaction": true,
      "signingDelaySeconds": 0,
      "spendingLimit": { "interval": "DAILY", "amount": "1000", "currency": "USD" }
    }
  ]
}'

# View platform key status
nunchuk sandbox platform-key get <sandbox-id>

# After finalization: view wallet platform key policies
nunchuk wallet platform-key get <wallet-id>

# Request a wallet platform key policy update
nunchuk wallet platform-key update <wallet-id> \
  --auto-broadcast --signing-delay 24h

# List pending dummy transactions (created when policy changes need approval)
nunchuk wallet dummy-tx list <wallet-id>

# Sign a dummy transaction to approve a policy change
nunchuk wallet dummy-tx sign <wallet-id> \
  --dummy-tx-id <id> --xprv <tprv...>

Commands

For full command documentation, see docs/cli-reference.md.

auth

| Command | Description | |---------|-------------| | auth login | Authenticate with API key (use --api-key for non-interactive login) | | auth status | Show authentication status for the selected network | | auth logout | Remove the stored API key for the selected network |

network

| Command | Description | |---------|-------------| | network set <network> | Set network (mainnet or testnet) | | network get | Show current network |

key

| Command | Description | |---------|-------------| | key generate | Generate a new BIP39 mnemonic and save locally | | key info | Derive signer info from a stored key, mnemonic, or xprv | | key list | List locally stored keys |

sandbox

| Command | Description | |---------|-------------| | sandbox create | Create a new group wallet sandbox | | sandbox list | List sandbox IDs | | sandbox get <id> | Get sandbox details from server | | sandbox join <id> | Join an existing sandbox | | sandbox add-key <id> | Add a signer key to a slot | | sandbox finalize <id> | Finalize sandbox into an active wallet | | sandbox delete <id> | Delete a sandbox | | sandbox platform-key enable <id> | Enable platform key on a sandbox | | sandbox platform-key disable <id> | Disable platform key on a sandbox | | sandbox platform-key set-policy <id> | Set platform key policies | | sandbox platform-key get <id> | Get platform key status and policies |

invitation

| Command | Description | |---------|-------------| | invitation send <sandbox-id> <emails...> | Invite participants by email | | invitation list [sandbox-id] | List invitations for the current user or a sandbox | | invitation accept <id> | Accept an invitation and join its sandbox | | invitation deny <id> | Deny an invitation |

wallet

| Command | Description | |---------|-------------| | wallet list | List wallets | | wallet get <id> | Get wallet details | | wallet address get <id> | Get a new receive address | | wallet export <id> | Export wallet descriptor and/or BSMS record | | wallet delete <id> | Delete a wallet | | wallet rename <id> | Rename a wallet locally | | wallet recover | Recover a wallet from a descriptor or BSMS backup file | | wallet platform-key get <id> | Get platform key policies for a wallet | | wallet platform-key update <id> | Request a platform key policy update | | wallet dummy-tx list <id> | List pending dummy transactions | | wallet dummy-tx get <id> | Get dummy transaction details | | wallet dummy-tx sign <id> | Sign a dummy transaction | | wallet dummy-tx cancel <id> | Cancel a dummy transaction |

tx

| Command | Description | |---------|-------------| | tx create | Create a new transaction | | tx sign | Sign a transaction locally (auto-detect, --fingerprint, or --xprv), or merge a signed PSBT with --psbt | | tx broadcast | Broadcast a fully signed transaction | | tx list | List transactions for a wallet | | tx get | Get transaction details |

tx create

nunchuk tx create --wallet <id> --to <address> --amount <sats>

Fee rate is automatically estimated from the Nunchuk API.

tx sign

nunchuk tx sign --wallet <id> --tx-id <txid>                             # auto-detect
nunchuk tx sign --wallet <id> --tx-id <txid> --fingerprint <xfp>         # specific key
nunchuk tx sign --wallet <id> --tx-id <txid> --xprv <extended-private-key>
nunchuk tx sign --wallet <id> --tx-id <txid> --psbt <signed-psbt-base64> # merge signed PSBT

tx broadcast

nunchuk tx broadcast --wallet <id> --tx-id <txid>

config

| Command | Description | |---------|-------------| | config show | Display current configuration | | config electrum get | Show the active Electrum server for the selected network | | config electrum set <server> | Persist a custom Electrum server (host:port, tcp://host:port, or ssl://host:port) | | config electrum reset | Reset the Electrum server to the selected network default |

Mainnet now defaults to ssl://mainnet.nunchuk.io:52002. When the protocol is omitted, the CLI tries ssl:// first, then tcp://, and only saves the server if the Electrum connection succeeds.

currency

| Command | Description | |---------|-------------| | currency convert <amount> <from> <to> | Convert between BTC, sat, USD, and fiat currencies |

Global Options

| Option | Description | |--------|-------------| | --json | Output in JSON format | | --api-key <key> | Override stored API key | | --network <network> | Override network for this command |

Project Structure

src/
  commands/         # CLI command definitions
    auth.ts         # Authentication commands
    config.ts       # Config and Electrum endpoint commands
    key.ts          # Key generation and derivation
    network.ts      # Network selection
    sandbox.ts      # Sandbox lifecycle (create, add-key, finalize, etc.)
    tx.ts           # Transaction commands (create, sign, broadcast, list, get)
    currency.ts     # Currency conversion commands
    wallet.ts       # Wallet management and export
  core/             # Business logic (importable as library)
    address.ts      # Bitcoin address derivation (multisig)
    api-client.ts   # HTTP client for Nunchuk API
    config.ts       # Config file management (~/.nunchuk-cli/config.json)
    crypto.ts       # NaCl encryption (Publicbox, Secretbox)
    descriptor.ts   # Bitcoin output descriptor builder + checksum
    electrum.ts     # Electrum protocol client
    format.ts       # Formatting utilities (BTC, sats, dates)
    keygen.ts       # BIP39 mnemonic generation and BIP32 key derivation
    platform-key.ts # Platform key types, validation, policy builders
    sandbox.ts      # Sandbox event builders (create, add-key, finalize, platform-key)
    storage.ts      # Local encrypted per-account SQLite storage (sandboxes, wallets, keys)
    transaction.ts  # Transaction operations (create, upload, fetch, broadcast)
    types.ts        # Shared types (AddressType)
    wallet-keys.ts  # BIP32/BIP85 key derivation (Secretbox key, GID, signing)
  index.ts          # CLI entry point
  output.ts         # Output formatting (human-readable / JSON)

Development

# Run in dev mode (no build needed)
npm run dev -- auth status

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format

# Build
npm run build

License

MIT — Copyright Nunchuk.