@nostrbox/cli

CLI tools for NIP-05 operations, BIP39 zodiac seed phrase management, and multi-chain key derivation.

Installation

From npm

npm install -g @nostrbox/cli

Shell Completion

After installation, enable tab completion for any command:

# Install completion for any command
bip39zodiac install
bip39keys install

# Restart your shell or source your profile
# Tab completion will now work for all commands

From source (development)

# Clone the repository and navigate to CLI directory
cd cli

# Install dependencies
npm install

# Build the TypeScript files
npm run build

# Install globally from source
npm install -g .

The commands will then be available globally:

• nip05lookup
• nip05check
• bip39zodiac
• bip39keys

Commands

nip05lookup

Purpose: Look up a single NIP-05 identifier and retrieve pubkey/relay information.

Usage:

nip05lookup <identifier>

Options:

• -t, --type <format> - Output format: hex, bech32, relays, or all (default)

Examples:

# Get all information (hex, npub, relays) 
nip05lookup [email protected]

# Get only hex pubkey
nip05lookup -t hex [email protected]

# Get only npub (bech32)
nip05lookup -t bech32 [email protected]

# Domain-only lookup (equivalent to [email protected])
nip05lookup domain.com

nip05check

Purpose: Validate an entire domain's NIP-05 setup and check all entries.

Usage:

nip05check <domain>

What it checks:

• Well-known directory existence
• nostr.json file validity
• Entry count and format
• Relay reachability

Example:

nip05check domain.com

bip39keys

Purpose: Derive cryptocurrency addresses from BIP39 mnemonic phrases for multiple blockchains.

Usage:

bip39keys --mnemonic "word1 word2 ..." --chain <chain> [OPTIONS]
bip39keys --load <file> --chain <chain> [OPTIONS]
bip39keys <install|uninstall>

Input Methods (choose one):

• --mnemonic "content" - BIP39 mnemonic phrase (12-24 words in quotes)
• --load <file> - Load mnemonic from file

Required Options:

• --chain <chain> - Blockchain to derive keys for
  • Choices: bitcoin, ethereum, solana, tron, nostr

Format Options:

• --format <formats> - Output format(s), comma-separated for multiple
  • Bitcoin: legacy, nested, native, taproot
  • Ethereum/Solana/TRON: native
  • Nostr: hex, bech32
  • Default: native (bitcoin/ethereum/solana/tron), hex (nostr)

Derivation Options:

• --account <index> - Account index (default: 0)
• --change <index> - Change index (default: 0)
• --address <index> - Address index (default: 0)
• --passphrase <text> - Optional BIP39 passphrase

Output Options:

• --save <file> - Save results to file

Commands:

• install - Install shell completion
• uninstall - Uninstall shell completion

Examples:

# Basic Bitcoin address
bip39keys --mnemonic "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" --chain bitcoin

# Multiple Bitcoin formats
bip39keys --mnemonic "abandon abandon..." --chain bitcoin --format legacy,native,taproot

# Ethereum address
bip39keys --mnemonic "abandon abandon..." --chain ethereum

# Solana address
bip39keys --mnemonic "abandon abandon..." --chain solana

# TRON address
bip39keys --mnemonic "abandon abandon..." --chain tron

# Nostr keys with both formats
bip39keys --mnemonic "abandon abandon..." --chain nostr --format hex,bech32

# Load from file with custom derivation path
bip39keys --load seed.txt --chain bitcoin --format native --account 1 --address 5

# With passphrase and save to file
bip39keys --mnemonic "abandon abandon..." --chain bitcoin --passphrase "secret" --save keys.txt

# Install shell completion
bip39keys install

File Formats: Input files can contain mnemonic phrases in two formats:

1. Space-separated on single line: word1 word2 word3 ...
2. One word per line

Derivation Paths:

• Bitcoin: m/44'/0'/account'/change/address (legacy), m/49'/0'/account'/change/address (nested), m/84'/0'/account'/change/address (native), m/86'/0'/account'/change/address (taproot)
• Ethereum: m/44'/60'/account'/change/address
• Solana: m/44'/501'/account' (default, Phantom-style) or m/44'/501'/account'/change'/address' (Ledger-style)
• TRON: m/44'/195'/account'/change/address
• Nostr: m/44'/1237'/account'/change/address

Supported Mnemonic Lengths: 12, 24 words (BIP39 standard)

bip39zodiac

Purpose: Transform BIP39 seed phrases into secret codes using zodiac-based shuffling, color offsets, and encryption for enhanced security.

Usage:

# Generation
bip39zodiac [INPUT_METHOD] [CONVERSION_FLAGS]

# Restoration
bip39zodiac [RESTORE_METHOD] --restore [CONVERSION_FLAGS]

# Commands
bip39zodiac <install|uninstall>

Input Methods for Generation (choose one):

• --new - Generate new random 12-word seed phrase
• --seed "words" - Transform existing seed phrase (12 words)
• --load --seed <file> - Load seed phrase from file

Restore Methods (choose one, use with --restore):

• --codes "numbers" - Secret codes: provide numbers directly
• --load --codes <file> - Secret codes: load from file
• --zodiacPwd "base58" - Plain zodiac password: provide Base58 directly
• --load --zodiacPwd <file> - Plain zodiac password: load from file
• --encZodiacPwd "encrypted" - Encrypted zodiac password: provide string directly
• --load --encZodiacPwd <file> - Encrypted zodiac password: load from file
• --encZodiacPwdSplit "part1,part2" - Encrypted split parts: comma-separated
• --load --encZodiacPwdSplit <file> - Encrypted split parts: load from file (2 lines or 1 line with comma)

Conversion Flags (all required):

• --operation <add|subtract> - Operation type (mandatory):
  • add - Add offsets (+)
  • subtract - Subtract offsets (-)
• --birthday <1-31> - Birthday day number (mandatory)
• --zodiac <sign> - Zodiac sign for shuffling (mandatory)
• --color <color> - Color for additional offset (mandatory):
  • blue(1), green(2), purple(3), orange(4), yellow(5), pink(6), brown(7)

Output Options:

• --zodiac-password - Output zodiac password (Base58) format
• --export <file> - Export JSON with encrypted split parts and public addresses (Bitcoin, Ethereum, Solana, TRON, Nostr)
• --save <file> - Save results to file

Commands:

• install - Install shell tab completion
• uninstall - Remove shell tab completion

Examples:

# Generate new seed phrase and transform it
bip39zodiac --new --operation=add --birthday=17 --zodiac=aries --color=blue

# Transform existing seed phrase and save codes
bip39zodiac --seed "abandon ability able..." --operation=subtract --birthday=25 --zodiac=leo --color=green --save codes.txt

# Export JSON with encrypted split parts and all chain addresses
bip39zodiac --new --export wallet.json --operation=add --birthday=17 --zodiac=aries --color=blue

# Restore from codes
bip39zodiac --codes "22 23 24 25 26 27 28 29 30 19 20 21" --restore --operation=add --birthday=17 --zodiac=aries --color=blue

# Restore from plain zodiac password
bip39zodiac --zodiacPwd "1P1Q1R1S1T1U1V1W1X1L1M1N" --restore --operation=add --birthday=17 --zodiac=aries --color=blue

# Restore from encrypted split parts
bip39zodiac --encZodiacPwdSplit "part1,part2" --restore --operation=add --birthday=17 --zodiac=aries --color=blue

# Load codes from file and restore
bip39zodiac --load --codes codes.txt --restore --operation=add --birthday=17 --zodiac=aries --color=blue

# Install shell completion
bip39zodiac install

Security Warning: Use a family member's birthday, a celebrity zodiac, or another memorable combination. Not your own birthday and zodiac for maximum security.

How It Works

BIP39 Keys

The BIP39 Keys system derives cryptocurrency addresses from mnemonic phrases:

1. Validation: Verifies BIP39 mnemonic checksum and word count (12-24 words)
2. Seed Generation: Converts mnemonic + optional passphrase to 512-bit seed using PBKDF2
3. HD Derivation: Uses BIP32/BIP44 hierarchical deterministic derivation
4. Address Generation: Creates addresses in various formats per blockchain

Supported Chains:

• Bitcoin: Legacy (P2PKH), Nested SegWit (P2SH-P2WPKH), Native SegWit (P2WPKH), Taproot (P2TR)
• Ethereum: EIP-55 checksummed addresses
• Solana: Base58-encoded Ed25519 public keys (Phantom and Ledger derivation paths)
• TRON: Base58Check-encoded addresses
• Nostr: x-only public keys in hex and bech32 (npub) formats

Security Features:

• Uses audited cryptographic libraries (@scure/bip39, @noble/secp256k1)
• Standard BIP32/BIP44 derivation paths
• Support for BIP39 passphrases
• Deterministic and reproducible results

BIP39 Zodiac

The BIP39 Zodiac system transforms seed phrases through a multi-step process:

1. Convert: Words → BIP39 indices (0-2047)
2. Birthday Offset: Add or subtract birthday value (1-31) with wraparound
3. Color Offset: Add or subtract color value (1-7) with wraparound
4. Shuffle: Apply zodiac-specific deterministic shuffle
5. Encode: Convert to Base58 zodiac password
6. Encrypt: Encrypt using memory keys (color + birthday + zodiac)
7. Split: Split encrypted password at position (birthday + color) for secure storage

Zodiac Shuffle Algorithms:

• aries: Move first 3 positions to end
• taurus: Reverse the entire list
• gemini: Swap first and second halves
• cancer: Alternate from ends inward
• leo: From middle, alternating extremes
• virgo: Reverse 4 segments of 3
• libra: Even positions first, then odd
• scorpio: Swap every pair
• sagittarius: Last 3 become first 3
• capricorn: Rotate 3 groups of 4
• aquarius: Swap segment pairs
• pisces: Second half + mirrored first

Color Values:

• blue: 1
• green: 2
• purple: 3
• orange: 4
• yellow: 5
• pink: 6
• brown: 7

Security Features:

• Cryptographically secure generation
• Deterministic and fully reversible
• Uses standard BIP39 wordlist
• Operation-based (add/subtract) with color offset
• AES-256 encryption with memory-derived keys
• Split storage for enhanced security
• Same parameters for both transform and restore (auto-reverses)
• Multiple restore methods for flexibility

Export Feature:

The --export option generates a JSON file containing:

• Encrypted split parts (encZodiacPwdSplit1, encZodiacPwdSplit2)
• Public addresses for all supported chains (Bitcoin, Ethereum, Solana, TRON, Nostr)

This provides a convenient backup format with:

• Secure storage via encrypted split parts
• Immediate address verification without restoring the seed
• Multi-chain address recovery from a single export file

Example export format:

{
  "encZodiacPwdSplit1": "...",
  "encZodiacPwdSplit2": "...",
  "nostr": "npub1...",
  "bitcoin": "bc1q...",
  "ethereum": "0x...",
  "solana": "...",
  "tron": "T..."
}