@clawdvault/cli 0.1.1 → 0.1.2

package/README.md

@@ -1,5 +1,8 @@
 # @clawdvault/cli
 
+[![npm version](https://img.shields.io/npm/v/@clawdvault/cli.svg)](https://www.npmjs.com/package/@clawdvault/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Command-line interface for [ClawdVault](https://clawdvault.com) - a pump.fun-style token launchpad on Solana.
 
 ## Installation
@@ -16,7 +19,7 @@ npx @clawdvault/cli tokens list
 
 ## Quick Start
 
-### Setup Wallet
+### 1. Setup Wallet
 
 ```bash
 # Generate a new wallet
@@ -26,7 +29,7 @@ clawdvault wallet init
 export CLAWDVAULT_WALLET=~/.config/solana/id.json
 ```
 
-### Read Operations (No Wallet Required)
+### 2. Read Operations (No Wallet Required)
 
 ```bash
 # List featured tokens
@@ -42,7 +45,7 @@ clawdvault trade quote -m TOKEN_MINT_ADDRESS -t buy -a 0.1
 clawdvault wallet sol-price
 ```
 
-### Write Operations (Wallet Required)
+### 3. Write Operations (Wallet Required)
 
 ```bash
 # Create a new token
@@ -56,28 +59,137 @@ clawdvault trade sell --mint TOKEN_MINT_ADDRESS --amount 1000000
 
 # Sell by percentage
 clawdvault trade sell --mint TOKEN_MINT_ADDRESS --percent 50
+```
+
+## Commands Reference
+
+### `clawdvault tokens`
+
+List and filter tokens.
 
-# Native SOL transfer
-clawdvault wallet transfer --to RECIPIENT_ADDRESS --sol 0.5
+```bash
+clawdvault tokens list [options]
+
+Options:
+  -s, --sort <field>     Sort by: created_at, market_cap, volume, price
+  -p, --page <number>    Page number (default: 1)
+  -l, --limit <number>   Items per page (default: 20)
+  --graduated            Show only graduated tokens
+  --not-graduated        Show only non-graduated tokens
+  --json                 Output as JSON
+
+Examples:
+  clawdvault tokens list --sort market_cap --limit 10
+  clawdvault tokens list --graduated --json
 ```
 
-### Wallet Operations
+### `clawdvault token`
+
+Token details and creation.
 
 ```bash
-# Show wallet info
-clawdvault wallet info
+# Get token details
+clawdvault token get <mint> [--json]
 
-# Check SOL balance
-clawdvault wallet sol-balance
+# Create a new token
+clawdvault token create [options]
+  -n, --name <name>           Token name (required)
+  -s, --symbol <symbol>       Token symbol (required)
+  -d, --description <desc>    Description
+  -i, --image <path>          Image file path (png, jpg, gif)
+  --initial-buy <sol>         Initial buy amount in SOL
+  --twitter <url>             Twitter URL
+  --telegram <url>            Telegram URL
+  --website <url>             Website URL
+  -w, --wallet <path>         Wallet file path
+
+# Get on-chain stats
+clawdvault token stats <mint> [--json]
+
+# Get top holders
+clawdvault token holders <mint> [--json]
+
+Examples:
+  clawdvault token get 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
+  clawdvault token create -n "Moon Token" -s "MOON" -i ./moon.png
+  clawdvault token create --name "Test" --symbol "TEST" --initial-buy 0.5
+```
+
+### `clawdvault trade`
+
+Buy, sell, and get quotes.
+
+```bash
+# Buy tokens
+clawdvault trade buy [options]
+  -m, --mint <address>     Token mint address (required)
+  -a, --sol <amount>       SOL amount to spend (required)
+  -s, --slippage <percent> Slippage tolerance (default: 1)
+  -w, --wallet <path>      Wallet file path
+  --simulate               Simulate only, don't execute
+
+# Sell tokens
+clawdvault trade sell [options]
+  -m, --mint <address>     Token mint address (required)
+  -a, --amount <tokens>    Token amount to sell
+  -p, --percent <percent>  Percentage of holdings to sell
+  -s, --slippage <percent> Slippage tolerance (default: 1)
+  -w, --wallet <path>      Wallet file path
+  --simulate               Simulate only, don't execute
+
+Note: Use either --amount or --percent, not both.
+
+# Get price quote
+clawdvault trade quote [options]
+  -m, --mint <address>     Token mint address (required)
+  -t, --type <type>        Quote type: buy or sell (required)
+  -a, --amount <amount>    Amount (SOL for buy, tokens for sell)
+  --json                   Output as JSON
+
+# View trade history
+clawdvault trade history [options]
+  -m, --mint <address>     Token mint address (required)
+  -l, --limit <number>     Number of trades (default: 20)
+  --json                   Output as JSON
+
+Examples:
+  clawdvault trade buy -m TOKEN_MINT -a 0.1
+  clawdvault trade buy -m TOKEN_MINT -a 0.5 -s 2 --simulate
+  clawdvault trade sell -m TOKEN_MINT -p 50
+  clawdvault trade sell -m TOKEN_MINT -a 1000000
+  clawdvault trade quote -m TOKEN_MINT -t buy -a 0.1
+```
+
+### `clawdvault wallet`
+
+Wallet management and info.
+
+```bash
+# Show wallet info (address, SOL balance)
+clawdvault wallet info [-w, --wallet <path>]
+
+# Generate new wallet
+clawdvault wallet init [-o, --output <path>] [--force]
+  Default output: ~/.clawdvault/wallet.json
+
+# Get wallet address only
+clawdvault wallet address [-w, --wallet <path>]
 
 # Check token balance
-clawdvault wallet balance -m TOKEN_MINT_ADDRESS
+clawdvault wallet balance -m, --mint <address> [-w, --wallet <path>]
 
-# Get deposit address
-clawdvault wallet address
+# Network status
+clawdvault wallet network [--json]
 
-# Request devnet SOL (devnet only)
-clawdvault wallet airdrop --sol 1
+# Current SOL/USD price
+clawdvault wallet sol-price [--json]
+
+Examples:
+  clawdvault wallet init
+  clawdvault wallet init -o ~/my-wallet.json
+  clawdvault wallet info
+  clawdvault wallet balance -m TOKEN_MINT
+  clawdvault wallet address
 ```
 
 ## Configuration
@@ -85,24 +197,34 @@ clawdvault wallet airdrop --sol 1
 ### Environment Variables
 
 ```bash
-# Wallet path
+# Wallet path (overrides default locations)
 export CLAWDVAULT_WALLET=~/.config/solana/id.json
 
 # Custom API endpoint
 export CLAWDVAULT_API_URL=https://clawdvault.com/api
 
-# Solana RPC (default: mainnet)
+# Solana RPC endpoint (default: mainnet)
+export SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+# For devnet testing:
 export SOLANA_RPC_URL=https://api.devnet.solana.com
 ```
 
+### Wallet Lookup Order
+
+1. `--wallet` / `-w` flag
+2. `CLAWDVAULT_WALLET` environment variable
+3. `~/.clawdvault/wallet.json`
+4. `~/.config/solana/id.json` (Solana CLI default)
+
 ### Global Options
 
 All commands support:
 
 ```bash
--w, --wallet <path>    # Specify wallet file
---rpc <url>            # Specify RPC endpoint
---json                 # Output as JSON
+-w, --wallet <path>    Specify wallet file
+--rpc <url>            Specify RPC endpoint  
+--json                 Output as JSON (where applicable)
+-h, --help             Show help
 ```
 
 ## Examples
@@ -113,34 +235,129 @@ All commands support:
 # 1. Generate wallet (first time only)
 clawdvault wallet init
 
-# 2. Check your address
+# 2. Check your address and fund with SOL
 clawdvault wallet address
+# Send SOL to this address from an exchange or another wallet
 
-# 3. Fund with SOL (or use airdrop on devnet)
-clawdvault wallet airdrop --sol 2
+# 3. Verify SOL balance
+clawdvault wallet info
 
-# 4. Create token
+# 4. Create your token
 clawdvault token create \
   --name "Moon Shot" \
   --symbol "MOON" \
-  --description "To the moon!" \
+  --description "To the moon! 🚀" \
   --image ./moon.png \
-  --twitter @moonshot \
-  --website https://moonshot.io
+  --twitter https://twitter.com/moonshot \
+  --website https://moonshot.io \
+  --initial-buy 0.1
 
-# 5. Check your token
+# 5. Check your new token
 clawdvault token get YOUR_TOKEN_MINT
 
-# 6. Buy more (optional)
-clawdvault trade buy --mint YOUR_TOKEN_MINT --sol 0.5
+# 6. View it on ClawdVault
+echo "https://clawdvault.com/token/YOUR_TOKEN_MINT"
+```
+
+### Trading Workflow
+
+```bash
+# Get a quote first
+clawdvault trade quote -m TOKEN_MINT -t buy -a 0.5
+
+# Simulate the trade (dry run)
+clawdvault trade buy -m TOKEN_MINT -a 0.5 --simulate
+
+# Execute the trade
+clawdvault trade buy -m TOKEN_MINT -a 0.5
+
+# Check your balance
+clawdvault wallet balance -m TOKEN_MINT
+
+# Take profits - sell 25%
+clawdvault trade sell -m TOKEN_MINT -p 25
+
+# Or sell specific amount
+clawdvault trade sell -m TOKEN_MINT -a 500000
+```
+
+### Monitoring
+
+```bash
+# Check token stats
+clawdvault token stats TOKEN_MINT --json
+
+# View recent trades
+clawdvault trade history -m TOKEN_MINT -l 50
+
+# Check top holders
+clawdvault token holders TOKEN_MINT
 ```
 
 ## Network Support
 
-- **Mainnet**: Production trading with real SOL
-- **Devnet**: Free testing with faucet SOL
+| Network | RPC URL | Notes |
+|---------|---------|-------|
+| Mainnet | `https://api.mainnet-beta.solana.com` | Production (default) |
+| Devnet | `https://api.devnet.solana.com` | Free testing |
+
+```bash
+# Use devnet for testing
+export SOLANA_RPC_URL=https://api.devnet.solana.com
+clawdvault tokens list
+```
+
+## Troubleshooting
+
+### "Error: Wallet not found"
+```bash
+# Generate a new wallet
+clawdvault wallet init
+
+# Or set path to existing wallet
+export CLAWDVAULT_WALLET=~/.config/solana/id.json
+```
+
+### "Error: Insufficient SOL balance"
+Your wallet needs SOL for transaction fees:
+```bash
+clawdvault wallet info  # Check balance
+# Fund your wallet address with SOL
+```
+
+### "Error: Slippage exceeded"
+Price moved during transaction. Increase slippage:
+```bash
+clawdvault trade buy -m MINT -a 0.1 -s 5  # 5% slippage
+```
+
+### "Error: Token not found"
+- Verify the mint address is correct
+- Token may not be indexed yet (wait a few seconds after creation)
+
+### Transaction stuck/pending
+- Solana network may be congested
+- Check transaction on [Solscan](https://solscan.io)
+- Try again with higher priority fee (coming soon)
+
+### Debug mode
+Add `DEBUG=clawdvault:*` for verbose logging:
+```bash
+DEBUG=clawdvault:* clawdvault trade buy -m MINT -a 0.1
+```
+
+## Programmatic Usage
+
+You can also use the CLI from Node.js scripts:
+
+```typescript
+import { execSync } from 'child_process';
+
+const result = execSync('clawdvault tokens list --json', { encoding: 'utf-8' });
+const tokens = JSON.parse(result);
+```
 
-Use `--rpc https://api.devnet.solana.com` or set `SOLANA_RPC_URL` for devnet.
+For more control, use the [@clawdvault/sdk](https://www.npmjs.com/package/@clawdvault/sdk) package directly.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdvault/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI for ClawdVault - Solana token launchpad",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@clawdvault/sdk": "^0.1.1",
+    "@clawdvault/sdk": "^0.1.2",
     "@solana/spl-token": "^0.4.0",
     "@solana/web3.js": "^1.91.0",
     "bs58": "^5.0.0",