@beclab/olaresid 0.1.1 → 0.1.3

package/CLI.md

@@ -0,0 +1,1300 @@
+# OlaresID CLI Tool
+
+A comprehensive command-line interface for managing OlaresID domains, RSA keys, IP records, operators, domain transfers, and cryptographic utilities.
+
+## Installation
+
+```bash
+npm install -g olaresid
+# or use npx
+npx olaresid <command>
+```
+
+## Quick Start
+
+```bash
+# Get help
+did-cli help
+
+# Query domain information
+did-cli info example.olares.com
+
+# Get domain owner
+did-cli owner example.olares.com
+```
+
+## Commands Overview
+
+### Query Commands
+
+#### Get Domain Metadata
+
+```bash
+did-cli info <domain> [options]
+
+# Examples
+did-cli info example.olares.com
+did-cli info example.olares.com --json
+did-cli info example.olares.com --network mainnet
+```
+
+#### Get Domain Owner
+
+```bash
+did-cli owner <domain> [options]
+
+# Examples
+did-cli owner example.olares.com
+did-cli owner example.olares.com --json
+```
+
+#### Check Domain Ownership
+
+```bash
+did-cli is-owner <domain>
+
+# Examples
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...
+did-cli is-owner example.olares.com
+did-cli is-owner example.olares.com --json
+```
+
+### RSA Key Management
+
+#### Generate RSA Key Pair
+
+```bash
+did-cli rsa generate [options]
+
+# Examples
+did-cli rsa generate
+did-cli rsa generate --output ./my-key.pem
+did-cli rsa generate --key-length 4096 --output ./my-key.pem
+```
+
+**Output:**
+
+-   Public key: `<output-path>.pem` (PEM PKCS#8 format)
+-   Private key: `<output-path>-private.pem` (PEM PKCS#8 format)
+
+#### Get RSA Public Key
+
+```bash
+did-cli rsa get <domain> [options]
+
+# Examples
+did-cli rsa get example.olares.com
+did-cli rsa get example.olares.com --json
+did-cli rsa get example.olares.com --output ./public-key.pem
+```
+
+#### Set RSA Public Key
+
+```bash
+did-cli rsa set <domain> <pem-file>
+
+# Examples
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...
+did-cli rsa set example.olares.com ./public-key.pem
+did-cli rsa set example.olares.com ./public-key.pem --json
+```
+
+#### Remove RSA Public Key
+
+```bash
+did-cli rsa remove <domain>
+
+# Examples
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...
+did-cli rsa remove example.olares.com
+did-cli rsa remove example.olares.com --json
+```
+
+### IP Management
+
+#### Get IP Address (DNS A Record)
+
+```bash
+did-cli ip get <domain> [options]
+
+# Examples
+did-cli ip get example.olares.com
+did-cli ip get example.olares.com --json
+```
+
+#### Set IP Address
+
+```bash
+did-cli ip set <domain> <ipv4-address>
+
+# Examples
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...
+did-cli ip set example.olares.com 192.168.1.100
+did-cli ip set example.olares.com 192.168.1.100 --json
+```
+
+#### Remove IP Address
+
+```bash
+did-cli ip remove <domain>
+
+# Examples
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...
+did-cli ip remove example.olares.com
+did-cli ip remove example.olares.com --json
+```
+
+### Subdomain Management
+
+#### Register Subdomain
+
+Register a new subdomain under a parent domain. The subdomain will have its own owner (derived from a mnemonic) and inherit the parent's metadata settings.
+
+```bash
+did-cli subdomain register <parent-domain> <subdomain-label> [options]
+
+# Examples
+
+# Generate a new 12-word mnemonic automatically
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...  # Parent domain owner's private key
+did-cli subdomain register parent.com child
+
+# Generate a 24-word mnemonic
+did-cli subdomain register parent.com child --words 24
+
+# Use an existing mnemonic for subdomain owner
+export MNEMONIC="your twelve word mnemonic phrase here that will derive the keys"
+did-cli subdomain register parent.com child
+
+# JSON output
+did-cli subdomain register parent.com child --json
+
+# Use mainnet
+did-cli subdomain register parent.com child --network mainnet
+```
+
+**Important Notes:**
+
+1. **Authentication**: You need the parent domain owner's private key or mnemonic via `PRIVATE_KEY_OR_MNEMONIC` environment variable
+2. **Subdomain Owner Mnemonic**:
+    - Set via `MNEMONIC` environment variable to use an existing mnemonic
+    - If `MNEMONIC` is not set, a new one will be auto-generated and saved to `./subdomain-mnemonic.txt`
+    - The mnemonic derives the subdomain's owner address and DID
+    - **Save the mnemonic securely** - it's the only way to control the subdomain
+3. **Full Domain**: If you register `child` under `parent.com`, the full domain will be `child.parent.com`
+4. **Inheritance**: The subdomain inherits `note` and `allowSubdomain` settings from the parent
+
+**Output Example:**
+
+```
+🔑 Generated 12-word mnemonic:
+   abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
+
+⚠️  IMPORTANT: Save this mnemonic securely! It controls the subdomain.
+
+📋 Registering subdomain: child.parent.com
+⏳ Submitting transaction...
+
+✅ Subdomain registered successfully!
+
+════════════════════════════════════════════════════════════
+Registration Details:
+════════════════════════════════════════════════════════════
+Subdomain label:    child
+Full domain name:   child.parent.com
+Owner address:      0x9858EfFD232B4033E47d90003D41EC34EcaEda94
+DID:                did:key:z6MkvARmXmTXnwyJz9uXbzJjEVKVb9PegegGZMqiuQQCHzo2
+Transaction hash:   0xabcd1234...
+Gas used:           150000
+Block number:       12345678
+════════════════════════════════════════════════════════════
+
+🔗 View on block explorer:
+   https://sepolia-optimism.etherscan.io/tx/0xabcd1234...
+```
+
+### Domain Transfer
+
+Transfer domain ownership to a new owner. This operation involves two transactions:
+
+1. Transfer the NFT (domain) ownership
+2. Update the domain's DID to match the new owner's DID
+
+#### Transfer Domain Ownership
+
+```bash
+did-cli transfer <domain> [options]
+
+# Examples
+
+# Auto-generate new owner credentials (12-word mnemonic)
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...  # Current owner's private key
+did-cli transfer example.com
+
+# Auto-generate with 24-word mnemonic
+did-cli transfer example.com --words 24
+
+# Use specific mnemonic for new owner
+export MNEMONIC="new owner twelve word mnemonic phrase here"
+did-cli transfer example.com
+
+# JSON output
+did-cli transfer example.com --json
+
+# Use mainnet
+did-cli transfer example.com --network mainnet
+```
+
+**Important Notes:**
+
+1. **Authentication**: You need the current owner's private key or mnemonic via `PRIVATE_KEY_OR_MNEMONIC` environment variable
+2. **New Owner Mnemonic**:
+    - Set via `MNEMONIC` environment variable to use an existing mnemonic
+    - If `MNEMONIC` is not set, a new one will be auto-generated and saved to `./transfer-new-owner-mnemonic.txt`
+    - The mnemonic derives the new owner's address and DID
+    - **Save the new owner's mnemonic securely** - it's the only way to control the domain after transfer
+3. **Two Transactions**: The operation submits two transactions to the blockchain
+    - First: Transfer NFT ownership
+    - Second: Update domain DID
+4. **Irreversible**: Once transferred, the domain is controlled by the new owner
+
+**Output Example:**
+
+```
+🔑 Generated 12-word mnemonic for new owner:
+   abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
+
+⚠️  IMPORTANT: Save this mnemonic securely! It controls the domain.
+
+📋 Transferring domain: example.com
+⏳ Submitting transactions...
+
+✅ Domain transfer successful!
+
+Transaction Details:
+  Domain: example.com
+  New Owner: 0x9858EfFD232B4033E47d90003D41EC34EcaEda94
+  New DID: did:key:z6MkvARmXmTXnwyJz9uXbzJjEVKVb9PegegGZMqiuQQCHzo2
+  Transfer Tx: 0xabcd1234...
+  Set DID Tx: 0xefgh5678...
+
+🔑 New Owner Mnemonic (SAVE THIS!):
+   abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
+```
+
+### Crypto Utilities
+
+Generate and derive cryptographic keys from mnemonic phrases. These utilities work offline and don't require blockchain access.
+
+#### Generate Mnemonic
+
+Generate a new BIP39 mnemonic phrase. **The mnemonic is automatically saved to a file for security.**
+
+```bash
+did-cli crypto generate [options]
+
+# Examples
+did-cli crypto generate                    # 12-word mnemonic (default)
+did-cli crypto generate --words 12         # 12-word mnemonic
+did-cli crypto generate --words 24         # 24-word mnemonic
+did-cli crypto generate --output ./my-mnemonic.txt  # Custom output file
+did-cli crypto generate --json             # JSON output
+```
+
+**Output Example:**
+
+```
+🔑 Generated 12-word mnemonic
+📄 Mnemonic saved to: ./mnemonic.txt
+
+⚠️  SECURITY WARNING:
+  • Keep this mnemonic secure! It controls all derived keys!
+  • Store it in a safe place (paper backup, hardware wallet, etc.)
+  • Delete the file after copying to a secure location
+  • Command: rm ./mnemonic.txt
+
+💡 To use the mnemonic:
+  export MNEMONIC="$(cat ./mnemonic.txt)"
+```
+
+**Note:** The default output file is `./mnemonic.txt`. Use `--output` option to specify a different location.
+
+#### Get Ethereum Address from Mnemonic
+
+Derive an Ethereum address from a mnemonic phrase.
+
+**Requirements:** `MNEMONIC` environment variable must be set.
+
+```bash
+export MNEMONIC="your twelve word mnemonic phrase here"
+did-cli crypto address
+
+# JSON output
+did-cli crypto address --json
+```
+
+**Output Example:**
+
+```
+🏠 Ethereum Address:
+   0x9858EfFD232B4033E47d90003D41EC34EcaEda94
+```
+
+#### Get DID from Mnemonic
+
+Derive a DID (Decentralized Identifier) from a mnemonic phrase.
+
+**Requirements:** `MNEMONIC` environment variable must be set.
+
+```bash
+export MNEMONIC="your twelve word mnemonic phrase here"
+did-cli crypto did
+
+# JSON output
+did-cli crypto did --json
+```
+
+**Output Example:**
+
+```
+🆔 DID:
+   did:key:z6MkvARmXmTXnwyJz9uXbzJjEVKVb9PegegGZMqiuQQCHzo2
+```
+
+#### Get EVM Private Key from Mnemonic
+
+Derive an EVM-compatible private key from a mnemonic phrase. **The private key is automatically saved to a file.**
+
+**Requirements:** `MNEMONIC` environment variable must be set.
+
+```bash
+export MNEMONIC="your twelve word mnemonic phrase here"
+did-cli crypto privatekey
+
+# Specify output file
+did-cli crypto privatekey --output ./my-private-key.txt
+
+# JSON output
+did-cli crypto privatekey --json
+```
+
+**Output Example:**
+
+```
+🔑 EVM Private Key:
+   0x1ab42cc412b618bdea3a599e3c9bae199ebf030895b039e9db1e30dafb12b727
+
+📄 Private key saved to: ./private-key.txt
+
+⚠️  SECURITY WARNING:
+  • Keep this private key secure! Never share it!
+  • Delete the file after copying to a secure location
+  • Command: rm ./private-key.txt
+```
+
+**Note:** The default output file is `./private-key.txt`. Use `--output` option to specify a different location.
+
+#### Derive All Keys from Mnemonic
+
+Derive all keys (address, DID, and private key) from a mnemonic in one command. **All keys are automatically saved to a file.**
+
+**Requirements:** `MNEMONIC` environment variable must be set.
+
+```bash
+export MNEMONIC="your twelve word mnemonic phrase here"
+did-cli crypto derive
+
+# Specify output file
+did-cli crypto derive --output ./my-keys.txt
+
+# JSON output
+did-cli crypto derive --json
+```
+
+**Output Example:**
+
+```
+🔐 Derived Keys:
+  Address: 0x9858EfFD232B4033E47d90003D41EC34EcaEda94
+  DID: did:key:z6MkvARmXmTXnwyJz9uXbzJjEVKVb9PegegGZMqiuQQCHzo2
+  Private Key: 0x1ab42cc412b618bdea3a599e3c9bae199ebf030895b039e9db1e30dafb12b727
+
+📄 Keys saved to: ./derived-keys.txt
+
+⚠️  SECURITY WARNING:
+  • Keep these credentials secure! Never share them!
+  • Delete the file after copying to a secure location
+  • Command: rm ./derived-keys.txt
+```
+
+**File Content Example:**
+
+```
+Ethereum Address: 0x9858EfFD232B4033E47d90003D41EC34EcaEda94
+DID: did:key:z6MkvARmXmTXnwyJz9uXbzJjEVKVb9PegegGZMqiuQQCHzo2
+Private Key: 0x1ab42cc412b618bdea3a599e3c9bae199ebf030895b039e9db1e30dafb12b727
+```
+
+**Note:** The default output file is `./derived-keys.txt`. Use `--output` option to specify a different location.
+
+**Important Notes:**
+
+1. **Offline Operation**: All crypto utilities work offline and don't require network access
+2. **Deterministic**: Same mnemonic always produces the same keys
+3. **BIP39 Standard**: Uses standard BIP39 mnemonic generation
+4. **BIP44 Derivation**: Follows BIP44 standard for Ethereum key derivation (m/44'/60'/0'/0/0)
+5. **Ed25519 for DID**: Uses Ed25519 curve for DID key generation (compatible with TermiPass)
+6. **Security**:
+    - Never share your mnemonic or private key
+    - Store mnemonics securely (paper backup, hardware wallet, etc.)
+    - Be cautious when using `privatekey` and `derive` commands in shared environments
+
+### Wallet Management
+
+Manage EVM and Solana wallet addresses associated with your domain. These authenticated addresses can be used for various authorization and verification purposes.
+
+#### Add EVM Wallet
+
+Add an EVM wallet address to your domain's authenticated addresses.
+
+**Requirements:**
+
+-   `PRIVATE_KEY_OR_MNEMONIC` environment variable (domain owner's key for signing)
+-   `EVM_PRIVATE_KEY` environment variable (wallet to add)
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_DOMAIN_OWNER_KEY"
+export EVM_PRIVATE_KEY="0xWALLET_TO_ADD"
+did-cli wallet evm add example.com
+
+# With JSON output
+did-cli wallet evm add example.com --json
+
+# On mainnet
+did-cli wallet evm add example.com --network mainnet
+```
+
+**Output Example:**
+
+```
+💼 Adding EVM wallet to domain: example.com
+
+✅ EVM wallet added successfully!
+   Address: 0x9858EfFD232B4033E47d90003D41EC34EcaEda94
+   Transaction: 0x123abc...
+   Gas used: 150000
+```
+
+**Important Notes:**
+
+-   The EVM_PRIVATE_KEY is the wallet you want to add as an authenticated address
+-   The PRIVATE_KEY_OR_MNEMONIC is your domain owner's key for authorization
+-   The signature is valid for 1 hour from the timestamp
+-   Duplicate addresses will be rejected with a friendly error message
+
+#### Remove EVM Wallet
+
+Remove an EVM wallet address from your domain.
+
+**Requirements:**
+
+-   `PRIVATE_KEY_OR_MNEMONIC` environment variable (domain owner's key)
+-   `EVM_PRIVATE_KEY` environment variable (wallet to remove)
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_DOMAIN_OWNER_KEY"
+export EVM_PRIVATE_KEY="0xWALLET_TO_REMOVE"
+did-cli wallet evm remove example.com
+
+# With JSON output
+did-cli wallet evm remove example.com --json
+```
+
+#### List EVM Wallets
+
+List all EVM wallet addresses associated with a domain.
+
+**No authentication required** (read-only operation)
+
+```bash
+did-cli wallet evm list example.com
+
+# With JSON output
+did-cli wallet evm list example.com --json
+```
+
+**Output Example:**
+
+```
+📋 Listing EVM wallets for domain: example.com
+   Found 2 wallet(s):
+   1. 0x9858effd232b4033e47d90003d41ec34ecaeda94
+   2. 0x1234567890abcdef1234567890abcdef12345678
+```
+
+**JSON Output Example:**
+
+```json
+{
+    "domain": "example.com",
+    "wallets": [
+        "0x9858effd232b4033e47d90003d41ec34ecaeda94",
+        "0x1234567890abcdef1234567890abcdef12345678"
+    ],
+    "count": 2
+}
+```
+
+#### Add Solana Wallet
+
+Add a Solana wallet address to your domain's authenticated addresses.
+
+**Requirements:**
+
+-   `PRIVATE_KEY_OR_MNEMONIC` environment variable (domain owner's key)
+-   `SOLANA_PRIVATE_KEY` environment variable (wallet to add)
+
+**Solana Private Key Formats:**
+
+-   **Base58 format** (from Phantom wallet export): `"5J7W..."`
+-   **JSON array format**: `"[1,2,3,...]"` (64 bytes)
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_DOMAIN_OWNER_KEY"
+
+# Using base58 format (Phantom export)
+export SOLANA_PRIVATE_KEY="5J7WpQXHJkD3..."
+did-cli wallet solana add example.com
+
+# Using JSON array format
+export SOLANA_PRIVATE_KEY='[174,47,154,...]'
+did-cli wallet solana add example.com
+
+# With JSON output
+did-cli wallet solana add example.com --json
+```
+
+**Output Example:**
+
+```
+💼 Adding Solana wallet to domain: example.com
+
+✅ Solana wallet added successfully!
+   Address: 8aKDo9WRy9YyJD5ZjL6nF5zEqG1N4mPxB7sU2wVqT3cH
+   Transaction: 0x456def...
+   Gas used: 180000
+```
+
+#### Remove Solana Wallet
+
+Remove a Solana wallet address from your domain.
+
+**Requirements:**
+
+-   `PRIVATE_KEY_OR_MNEMONIC` environment variable (domain owner's key)
+-   `SOLANA_PRIVATE_KEY` environment variable (wallet to remove)
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_DOMAIN_OWNER_KEY"
+export SOLANA_PRIVATE_KEY="5J7WpQXHJkD3..."
+did-cli wallet solana remove example.com
+```
+
+#### List Solana Wallets
+
+List all Solana wallet addresses associated with a domain.
+
+**No authentication required** (read-only operation)
+
+```bash
+did-cli wallet solana list example.com
+
+# With JSON output
+did-cli wallet solana list example.com --json
+```
+
+**Output Example:**
+
+```
+📋 Listing Solana wallets for domain: example.com
+   Found 1 wallet(s):
+   1. 8aKDo9WRy9YyJD5ZjL6nF5zEqG1N4mPxB7sU2wVqT3cH
+```
+
+**Technical Details:**
+
+1. **Signature Verification**: Both EVM and Solana wallets use EIP-712 typed data signing for verification
+2. **Ed25519 Signatures**: Solana uses Ed25519 signatures for authentication
+3. **Timestamp Validation**: Signatures must be generated within 1 hour of the current time
+4. **Storage**: Wallet addresses are stored in the RootTagger2 contract
+5. **Backward Compatibility**: `list` command also fetches addresses from legacy RootResolver contract
+
+### Operator Management
+
+#### Get Operator Address
+
+```bash
+did-cli operator get [options]
+
+# Examples
+did-cli operator get
+did-cli operator get --json
+did-cli operator get --network mainnet
+```
+
+#### Set Operator Address
+
+```bash
+did-cli operator set <address>
+
+# Examples
+export PRIVATE_KEY_OR_MNEMONIC=0x1234...
+did-cli operator set 0x5678...
+did-cli operator set 0x5678... --json
+```
+
+### Utility Commands
+
+#### Convert PEM to DER
+
+```bash
+did-cli convert pem-to-der <pem-file> [options]
+
+# Examples
+did-cli convert pem-to-der ./public-key.pem
+did-cli convert pem-to-der ./public-key.pem --json
+did-cli convert pem-to-der ./public-key.pem --output ./key.der
+```
+
+#### Convert DER to PEM
+
+```bash
+did-cli convert der-to-pem <der-hex> [options]
+
+# Examples
+did-cli convert der-to-pem 0x3082010a...
+did-cli convert der-to-pem 0x3082010a... --json
+did-cli convert der-to-pem 0x3082010a... --output ./key.pem
+```
+
+#### Convert IPv4 to Bytes4
+
+```bash
+did-cli convert ip-to-bytes <ipv4-address> [options]
+
+# Examples
+did-cli convert ip-to-bytes 192.168.1.1
+did-cli convert ip-to-bytes 192.168.1.1 --json
+```
+
+#### Convert Bytes4 to IPv4
+
+```bash
+did-cli convert bytes-to-ip <bytes4-hex> [options]
+
+# Examples
+did-cli convert bytes-to-ip 0xc0a80101
+did-cli convert bytes-to-ip 0xc0a80101 --json
+```
+
+---
+
+## Tag Management Commands
+
+Tags are typed key-value pairs that can be attached to domains for storing structured metadata on-chain. The CLI provides simple commands for basic tag operations with common types.
+
+> **📖 For Advanced Usage**: For complex types (tuples/structs), array element operations, and detailed API documentation, see the [Tag System Documentation](./docs/TAG_SYSTEM.md) and check the [examples](./examples/) directory.
+
+### Define Tag Type
+
+Define a new tag with a specific type. Tags must be defined before they can be used.
+
+```bash
+did-cli tag define <domain> <tag-name> <type>
+```
+
+**Supported Types:**
+
+-   Simple types: `string`, `uint8`, `uint256`, `int8`, `int256`, `bool`, `address`, `bytes`, `bytes32`
+-   Array types: `"string[]"`, `"uint8[]"`, `"address[]"`, etc. (must be quoted!)
+
+**Requirements:** `PRIVATE_KEY_OR_MNEMONIC` environment variable
+
+**Examples:**
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_PRIVATE_KEY"
+
+# Define simple types
+did-cli tag define example.com email string
+did-cli tag define example.com age uint8
+did-cli tag define example.com verified bool
+did-cli tag define example.com owner address
+
+# Define array types (MUST be quoted!)
+did-cli tag define example.com wallets "address[]"
+did-cli tag define example.com socialLinks "string[]"
+
+# With JSON output
+did-cli tag define example.com followers uint256 --json
+```
+
+**Output Example:**
+
+```
+📝 Defining tag "email" for domain: example.com
+   Type: string
+
+✅ Tag "email" defined successfully
+   Transaction: 0x123abc...
+   Gas used: 150000
+```
+
+### Set Tagger
+
+Set the authorized address (tagger) that can modify a tag's value. Only the domain owner can set the tagger.
+
+```bash
+did-cli tag set-tagger <domain> <tag-name> <tagger-address>
+```
+
+**Requirements:** `PRIVATE_KEY_OR_MNEMONIC` environment variable
+
+**Examples:**
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_PRIVATE_KEY"
+
+# Set tagger to a specific address
+did-cli tag set-tagger example.com email 0x1234567890abcdef...
+
+# Set tagger to yourself
+SIGNER_ADDRESS=$(did-cli crypto address)
+did-cli tag set-tagger example.com email $SIGNER_ADDRESS
+```
+
+**Output Example:**
+
+```
+🔐 Setting tagger for tag "email" in domain: example.com
+   Tagger address: 0x1234567890abcdef...
+
+✅ Tagger set successfully
+   Transaction: 0x456def...
+```
+
+### Set Tag Value
+
+Set or update a tag's value. You must be the designated tagger for this tag.
+
+```bash
+did-cli tag set <domain> <tag-name> <value>
+```
+
+**Value Formats:**
+
+-   **Strings**: Direct input (`user@example.com`) or JSON string
+-   **Numbers**: Direct input (`30`, `1000`)
+-   **Booleans**: `true` or `false`
+-   **Arrays**: JSON format, must be quoted (`'["item1","item2"]'`)
+
+**Requirements:** `PRIVATE_KEY_OR_MNEMONIC` environment variable
+
+**Examples:**
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_PRIVATE_KEY"
+
+# Set string value
+did-cli tag set example.com email "user@example.com"
+did-cli tag set example.com bio "Web3 developer and blockchain enthusiast"
+
+# Set number value
+did-cli tag set example.com age 30
+did-cli tag set example.com followers 1350
+
+# Set boolean value
+did-cli tag set example.com verified true
+did-cli tag set example.com premium false
+
+# Set array value (use JSON, must be quoted!)
+did-cli tag set example.com socialLinks '["https://twitter.com/alice","https://github.com/alice"]'
+did-cli tag set example.com wallets '["0x1111111111111111111111111111111111111111","0x2222222222222222222222222222222222222222"]'
+
+# With JSON output
+did-cli tag set example.com email "user@example.com" --json
+```
+
+**Output Example:**
+
+```
+📝 Setting tag "email" for domain: example.com
+   Value: user@example.com
+
+✅ Tag "email" set successfully
+   Transaction: 0x789ghi...
+   Gas used: 120000
+```
+
+### Get Tag Value
+
+Read a tag's current value. This is a read-only operation and doesn't require authentication.
+
+```bash
+did-cli tag get <domain> <tag-name>
+```
+
+**Requirements:** None (read-only)
+
+**Examples:**
+
+```bash
+# Get any tag value
+did-cli tag get example.com email
+did-cli tag get example.com age
+did-cli tag get example.com socialLinks
+
+# With JSON output
+did-cli tag get example.com email --json
+```
+
+**Output Examples:**
+
+```
+📖 Getting tag "email" for domain: example.com
+
+✅ Tag value:
+   user@example.com
+```
+
+```
+📖 Getting tag "socialLinks" for domain: example.com
+
+✅ Tag value:
+   ["https://twitter.com/alice","https://github.com/alice"]
+```
+
+### Remove Tag Value
+
+Remove a tag's value while keeping its definition. The tag can be set again later.
+
+```bash
+did-cli tag remove <domain> <tag-name>
+```
+
+**Requirements:** `PRIVATE_KEY_OR_MNEMONIC` environment variable
+
+**Examples:**
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_PRIVATE_KEY"
+
+# Remove tag value
+did-cli tag remove example.com email
+
+# With JSON output
+did-cli tag remove example.com email --json
+```
+
+**Output Example:**
+
+```
+🗑️  Removing tag "email" for domain: example.com
+
+✅ Tag "email" value removed successfully
+   Transaction: 0xabc123...
+```
+
+**Note:** This removes the _value_ only, not the tag definition. The tag type remains defined and can be set again.
+
+### List All Tags
+
+List all tags and their current values for a domain.
+
+```bash
+did-cli tag list <domain>
+```
+
+**Requirements:** None (read-only)
+
+**Examples:**
+
+```bash
+# List all tags
+did-cli tag list example.com
+
+# With JSON output
+did-cli tag list example.com --json
+```
+
+**Output Example:**
+
+```
+📋 Listing all tags for domain: example.com
+
+✅ Found 7 tags:
+
+   Tag: "email"
+     Value: user@example.com
+   Tag: "age"
+     Value: 30
+   Tag: "verified"
+     Value: true
+   Tag: "bio"
+     Value: Web3 developer and blockchain enthusiast
+   Tag: "followers"
+     Value: 1350
+   Tag: "socialLinks"
+     Value: ["https://twitter.com/alice","https://github.com/alice"]
+   Tag: "wallets"
+     Value: ["0x1111111111111111111111111111111111111111"]
+```
+
+### List Defined Tag Types
+
+List all defined tag types for a domain, including those without values.
+
+```bash
+did-cli tag list-defined <domain>
+```
+
+**Requirements:** None (read-only)
+
+**Examples:**
+
+```bash
+# List defined tag types
+did-cli tag list-defined example.com
+
+# With JSON output
+did-cli tag list-defined example.com --json
+```
+
+**Output Example:**
+
+```
+📋 Listing defined tag types for domain: example.com
+
+✅ Found 9 defined tag types:
+
+   - email
+   - age
+   - verified
+   - bio
+   - followers
+   - premium
+   - socialLinks
+   - wallets
+   - userInfo
+```
+
+### Get Tagger
+
+Get the current tagger address for a tag.
+
+```bash
+did-cli tag get-tagger <domain> <tag-name>
+```
+
+**Requirements:** None (read-only)
+
+**Examples:**
+
+```bash
+# Get tagger address
+did-cli tag get-tagger example.com email
+
+# With JSON output
+did-cli tag get-tagger example.com email --json
+```
+
+**Output Example:**
+
+```
+🔍 Getting tagger for tag "email" in domain: example.com
+
+✅ Tagger address: 0x1234567890abcdef...
+```
+
+### Complete Tag Workflow Example
+
+```bash
+# 1. Set authentication
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_PRIVATE_KEY"
+
+# 2. Define tag types
+did-cli tag define example.com bio string
+did-cli tag define example.com followers uint256
+did-cli tag define example.com premium bool
+did-cli tag define example.com socialLinks "string[]"
+
+# 3. Get your address and set as tagger
+SIGNER_ADDRESS=$(did-cli crypto address)
+did-cli tag set-tagger example.com bio $SIGNER_ADDRESS
+did-cli tag set-tagger example.com followers $SIGNER_ADDRESS
+did-cli tag set-tagger example.com premium $SIGNER_ADDRESS
+did-cli tag set-tagger example.com socialLinks $SIGNER_ADDRESS
+
+# 4. Set tag values
+did-cli tag set example.com bio "Web3 developer and blockchain enthusiast"
+did-cli tag set example.com followers 1350
+did-cli tag set example.com premium true
+did-cli tag set example.com socialLinks '["https://twitter.com/alice","https://github.com/alice"]'
+
+# 5. Read values (no auth required)
+did-cli tag get example.com bio
+did-cli tag list example.com
+
+# 6. Update a value
+did-cli tag set example.com followers 1500
+
+# 7. Remove a value
+did-cli tag remove example.com premium
+```
+
+### Important Notes
+
+1. **Array Types Must Be Quoted**: When using array types like `address[]` or `string[]`, you must quote them to prevent shell interpretation:
+
+    ```bash
+    # ✅ Correct
+    did-cli tag define example.com wallets "address[]"
+
+    # ❌ Wrong - shell will interpret []
+    did-cli tag define example.com wallets address[]
+    ```
+
+2. **Array Values Must Be JSON**: When setting array values, use valid JSON and quote the entire value:
+
+    ```bash
+    # ✅ Correct
+    did-cli tag set example.com links '["https://twitter.com","https://github.com"]'
+
+    # ❌ Wrong
+    did-cli tag set example.com links https://twitter.com,https://github.com
+    ```
+
+3. **Set Tagger Before Setting Values**: You must set a tagger after defining a tag and before you can set its value:
+
+    ```bash
+    did-cli tag define example.com email string
+    did-cli tag set-tagger example.com email $YOUR_ADDRESS  # Required!
+    did-cli tag set example.com email "user@example.com"
+    ```
+
+4. **CLI Limitations**: The CLI only supports simple types and arrays. For complex tuple types and advanced operations:
+
+    - Use the SDK directly (see [TAG.md](./TAG.md))
+    - Check examples in [`examples/tag-management.ts`](./examples/tag-management.ts)
+
+5. **Tags Are Immutable After Definition**: You cannot change a tag's type once defined. You can only set/update/remove values.
+
+---
+
+## Global Options
+
+| Option | Description | Default |
+| --- | --- | --- |
+| `-n, --network <network>` | Network to use (sepolia\|mainnet) | sepolia |
+| `--rpc <url>` | Custom RPC endpoint URL | - |
+| `--contract-did <address>` | Custom DID contract address | - |
+| `--contract-resolver <address>` | Custom RootResolver contract address | - |
+| `--contract-abi <address>` | Custom ABIType contract address | - |
+| `--contract-resolver2 <address>` | Custom RootResolver2 contract address | - |
+| `--support-svc-url <url>` | Custom support service URL | - |
+| `-o, --output <file>` | Output file path | - |
+| `--key-length <bits>` | RSA key length in bits | 2048 |
+| `-w, --words <count>` | Mnemonic word count (12\|15\|18\|21\|24) | 12 |
+| `-j, --json` | Output in JSON format | false |
+| `-v, --verbose` | Enable verbose debug output | false |
+| `--debug` | Enable debug output | false |
+| `--debug-level <level>` | Set debug level (debug\|info\|warn\|error) | info |
+| `-h, --help` | Show help message | - |
+| `-V, --version` | Show version number | - |
+
+## Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `PRIVATE_KEY_OR_MNEMONIC` | Private key (0x...) or BIP39 mnemonic phrase for signing transactions (required for write operations like transfer, set RSA key, set IP, wallet management, etc.) |
+| `MNEMONIC` | BIP39 mnemonic phrase for generating owner identity (used in subdomain registration, domain transfer, and crypto utilities) |
+| `EVM_PRIVATE_KEY` | EVM wallet private key (0x...) for wallet management operations (required for `wallet evm add/remove` commands) |
+| `SOLANA_PRIVATE_KEY` | Solana wallet private key for wallet management operations (required for `wallet solana add/remove` commands). Supports base58 or JSON array format |
+
+**Security Note:** Using environment variables for private keys or mnemonics prevents them from being stored in shell history, which is more secure than passing them as command-line arguments.
+
+**Format Examples:**
+
+-   Private key: `export PRIVATE_KEY_OR_MNEMONIC=0x1234567890abcdef...`
+-   Mnemonic: `export PRIVATE_KEY_OR_MNEMONIC="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"`
+
+> **⚠️ Important: Always use quotes for mnemonic phrases!**
+>
+> Without quotes, the shell will only capture the first word:
+>
+> ```bash
+> # ❌ WRONG - Only captures "advice"
+> export PRIVATE_KEY_OR_MNEMONIC=advice wrestle recycle yellow light avoid shell mutual ketchup obscure game corn
+>
+> # ✅ CORRECT - Captures the entire phrase
+> export PRIVATE_KEY_OR_MNEMONIC="advice wrestle recycle yellow light avoid shell mutual ketchup obscure game corn"
+> ```
+
+## Network Configuration
+
+### Sepolia (Default)
+
+-   RPC: `https://sepolia.optimism.io`
+-   DID Contract: `0xe2D7c3a9013960E04d4E9F5F9B63fff37eEd97A8`
+-   RootResolver: `0xeF727cb066Fee98F88Db84555830063b4A24ddfc`
+-   ABI Type: `0x7386fCBae6Ad4CCE1499d9153D99bc950B589718`
+-   RootResolver2: `0xcbC02aa08c77a374eC0D5A0403E108b7573d96e8`
+-   Support Service: `https://api-test.olares.com/did/support`
+
+### Mainnet
+
+-   RPC: `https://optimism-rpc.publicnode.com`
+-   DID Contract: `0x5DA4Fa8E567d86e52Ef8Da860de1be8f54cae97D`
+-   RootResolver: `0xE2EABA0979277A90511F8873ae1e8cA26B54E740`
+-   ABI Type: `0x9ae3F16bD99294Af1784beB1a0A5C84bf2636365`
+-   RootResolver2: `0x50724411eb1817822e2590a43a8F0859FCc6fCD5`
+-   Support Service: `https://api.olares.com/did/support`
+
+## Output Formats
+
+### Human-Readable (Default)
+
+```bash
+$ did-cli info example.olares.com
+
+📋 Domain Metadata:
+  Name:            example.olares.com
+  DID:             did:key:z6Mkm...
+  Token ID:        1234567890123456789012345678901234567890
+  Note:            Individual:TerminusUser
+  Allow Subdomain: true
+```
+
+### JSON Format
+
+```bash
+$ did-cli info example.olares.com --json
+
+{
+  "name": "example.olares.com",
+  "did": "did:key:z6Mkm...",
+  "id": "1234567890123456789012345678901234567890",
+  "note": "Individual:TerminusUser",
+  "allowSubdomain": true
+}
+```
+
+## Examples
+
+### Complete Workflow: Register and Configure a Domain
+
+```bash
+# 1. Set your private key or mnemonic (do this once per session)
+export PRIVATE_KEY_OR_MNEMONIC=0x1234567890abcdef...
+# Or use mnemonic
+export PRIVATE_KEY_OR_MNEMONIC="your twelve word mnemonic phrase here"
+
+# 2. Check ownership
+did-cli is-owner example.olares.com
+
+# 3. Generate RSA key pair
+did-cli rsa generate --output ./example-key.pem --key-length 2048
+
+# 4. Set RSA public key
+did-cli rsa set example.olares.com ./example-key.pem
+
+# 5. Set IP address
+did-cli ip set example.olares.com 192.168.1.100
+
+# 6. Verify configuration
+did-cli info example.olares.com
+did-cli rsa get example.olares.com
+did-cli ip get example.olares.com
+```
+
+### Persisting Private Key Across Sessions
+
+```bash
+# Add to your ~/.bashrc or ~/.zshrc for persistence
+echo 'export PRIVATE_KEY_OR_MNEMONIC=0x1234567890abcdef...' >> ~/.bashrc
+source ~/.bashrc
+
+# Or use a .env file (recommended for development)
+echo 'PRIVATE_KEY_OR_MNEMONIC=0x1234567890abcdef...' > .env
+# Then load it before using CLI
+export $(cat .env | xargs)
+
+# Now you can use commands without setting PRIVATE_KEY_OR_MNEMONIC each time
+did-cli rsa set example.olares.com ./key.pem
+did-cli ip set example.olares.com 192.168.1.100
+did-cli operator set 0x5678...
+```
+
+### Batch Operations with JSON Output
+
+```bash
+# Query multiple domains
+for domain in example1.olares.com example2.olares.com; do
+  did-cli info $domain --json >> domains.json
+done
+
+# Process JSON output with jq
+did-cli info example.olares.com --json | jq '.owner'
+```
+
+## Error Handling
+
+The CLI provides clear error messages for common issues:
+
+```bash
+# Missing required argument
+$ did-cli info
+❌ Error: Domain argument is required
+Usage: did-cli info <domain>
+
+# Invalid IP address
+$ did-cli ip set example.olares.com invalid-ip
+❌ Error: Invalid IPv4 address format
+
+# Missing private key or mnemonic
+$ did-cli is-owner example.olares.com
+❌ Error: Private key or mnemonic is required for this operation
+Please set PRIVATE_KEY_OR_MNEMONIC environment variable
+Example: export PRIVATE_KEY_OR_MNEMONIC=0xYOUR_PRIVATE_KEY
+Or: export PRIVATE_KEY_OR_MNEMONIC="your twelve words..."
+```
+
+## Development
+
+### Run from Source
+
+```bash
+# Clone repository
+git clone https://github.com/olares/did-system.git
+cd did-system/packages/olaresid
+
+# Install dependencies
+npm install
+
+# Run CLI
+npx ts-node src/cli.ts <command>
+```
+
+### Debug Mode
+
+```bash
+# Enable verbose output
+did-cli info example.olares.com --verbose
+
+# Enable debug output with level
+did-cli info example.olares.com --debug --debug-level debug
+```
+
+## License
+
+See the main repository LICENSE file.