npm package: @nostrbox/cli
Description: CLI tool for NIP-05 operations and BIP39 zodiac seed phrase management using NostrBox core
Latest version: 1.8.1

# @nostrbox/cli

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

## Installation

### From npm

```bash
npm install -g @nostrbox/cli
```

### Shell Completion

After installation, enable tab completion for any command:

```bash
# 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)

```bash
# 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**:
```bash
nip05lookup <identifier>
```

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

**Examples**:
```bash
# Get all information (hex, npub, relays) 
nip05lookup john@domain.com

# Get only hex pubkey
nip05lookup -t hex john@domain.com

# Get only npub (bech32)
nip05lookup -t bech32 john@domain.com

# Domain-only lookup (equivalent to _@domain.com)
nip05lookup domain.com
```

### nip05check

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

**Usage**:
```bash
nip05check <domain>
```

**What it checks**:
- Well-known directory existence
- nostr.json file validity
- Entry count and format
- Relay reachability

**Example**:
```bash
nip05check domain.com
```

### bip39keys

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

**Usage**:
```bash
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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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:
```json
{
  "encZodiacPwdSplit1": "...",
  "encZodiacPwdSplit2": "...",
  "nostr": "npub1...",
  "bitcoin": "bc1q...",
  "ethereum": "0x...",
  "solana": "...",
  "tron": "T..."
}
```