@nostrbox/cli/README.md

CLI tool for NIP-05 operations and BIP39 zodiac seed phrase management using NostrBox core

# @nostrbox/cli

CLI tools for NIP-05 operations and BIP39 zodiac seed phrase management.

## Installation

### From npm

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

### Shell Completion

After installation, enable tab completion for any command:

```bash
# Install completion for bip39zodiac
bip39zodiac install

# Restart your shell or source your profile
# Tab completion will now work: bip39zodiac --ne<TAB> → --new
```

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

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

### bip39zodiac

**Usage**:
```bash
bip39zodiac [INPUT_METHOD] [OPTIONS] [CONVERSION_FLAGS]
bip39zodiac <install|uninstall>
```

**Input Methods** (choose one):
- `--new` - Generate new random 12-word seed phrase
- `--seed "words"` - Transform existing seed phrase
- `--load <file>` - Load from file

**Options**:
- `--restore` - Restore mode (reverses the transformation)
- `--save <file>` - Save results to file

**Conversion Flags** (all required):
- `--red` OR `--black` - Card color (exactly one required):
  - `--red` - Add birthday offset (+)
  - `--black` - Subtract birthday offset (-)
- `--birthday <1-31>` - Birthday day number
- `--zodiac <sign>` - Zodiac sign for shuffling

**Commands**:
- `install` - Install shell tab completion 
- `uninstall` - Remove shell tab completion

**Examples**:
```bash
# Generate new seed phrase and transform it
bip39zodiac --new --red --birthday=17 --zodiac=aries

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

# Restore from codes (same color auto-reverses)  
bip39zodiac --seed "1234 567 890..." --restore --red --birthday=17 --zodiac=aries

# Load and transform from file
bip39zodiac --load seedphrase.txt --red --birthday=10 --zodiac=virgo

# Install shell completion
bip39zodiac install
```

**Security Warning**: Use a family member's birthday and celebrity's zodiac sign, not your own, for maximum security.

## How It Works

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

1. **Convert**: Words → BIP39 indices (0-2047)
2. **Offset**: Add or subtract birthday (with wraparound)
3. **Shuffle**: Apply zodiac-specific deterministic shuffle

**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

**Security Features:**
- Cryptographically secure generation
- Deterministic and fully reversible
- Uses standard BIP39 wordlist
- Color-based operation (red=add, black=subtract)
- Same color for both transform and restore (auto-reverses)