httpcat-cli 0.0.27 → 0.1.0

package/README.md

@@ -1,4 +1,4 @@
-# httpcat CLI
+# httpcat-cli
 
 > 🐱 Command-line interface for interacting with the httpcat agent - create, buy, and sell tokens with x402 payments
 
@@ -125,13 +125,13 @@ httpcat> help
 Available Commands:
 
   create <name> <symbol>          Create a new token
-  buy <identifier> <amount>       Buy tokens ($0.05, $0.10, or $0.20)
-  sell <identifier> <amount|all>  Sell tokens
-  info <identifier>               Get token information
+  buy <id|name|symbol> <amount>   Buy tokens ($0.05, $0.10, or $0.20)
+  sell <id|name|symbol> <amount|all>  Sell tokens
+  info <id|name|symbol>           Get token information
   list [--sort mcap|created]      List all tokens
   positions                       Get all your positions with comprehensive info
-  chat [token]                    Start streaming chat (optional: token identifier)
-  balance                         Check wallet balance (ETH and USDC)
+  chat [token]                    Start streaming chat (optional: token symbol/name/address)
+  balances                        Check wallet balances (ETH and USDC)
   health                          Check agent health
   config [--show|--set|--reset]   Manage configuration
   network                          Show current network
@@ -150,14 +150,12 @@ httpcat> create "Meow Token" "MEOW"
 ┌─────────────────────────────────────────┐
 │ 🎉 Meow Token (MEOW)                    │
 ├─────────────────────────────────────────┤
-│ Token ID:  abc123-4567-89ab-cdef-...    │
 │ Address:   0x789abcd...                 │
 │ Supply:    1,000,000,000 MEOW           │
 │ Status:    Active                       │
 └─────────────────────────────────────────┘
 
-httpcat> buy 0x1234567890123456789012345678901234567890 0.20
-httpcat> buy abc123-4567-89ab-cdef-0123456789ab 0.20
+httpcat> buy 0x789abcd... 0.20
 
 💰 Tokens purchased successfully!
 
@@ -197,9 +195,9 @@ httpcat create "My Token" "MTK" --photo https://example.com/photo.png --website
 
 **Options:**
 
-- `--photo <url>` - Token photo URL
-- `--banner <url>` - Banner image URL
-- `--website <url>` - Website URL
+- `-p, --photo <url>` - Token photo URL
+- `-b, --banner <url>` - Banner image URL
+- `-w, --website <url>` - Website URL
 
 **Cost:** $0.01 USDC
 
@@ -210,8 +208,7 @@ Purchase tokens from the bonding curve.
 **Interactive:**
 
 ```bash
-httpcat> buy 0x1234567890123456789012345678901234567890 0.20
-httpcat> buy abc123-... 0.20
+httpcat> buy 0x1234... 0.20
 httpcat> buy "My Token" 0.10
 httpcat> buy MTK 0.05
 ```
@@ -219,36 +216,31 @@ httpcat> buy MTK 0.05
 **CLI:**
 
 ```bash
-httpcat buy 0x1234567890123456789012345678901234567890 0.20
-httpcat buy abc123-4567-89ab-cdef-0123456789ab 0.20
+httpcat buy 0x1234567890abcdef1234567890abcdef12345678 0.20
 httpcat buy "My Token" 0.10
 httpcat buy MTK 0.05
 ```
 
 **Options:**
 
-- `--repeat <count>` - Execute multiple buys in sequence (stops early if token graduates or insufficient funds)
-- `--delay <ms>` - Delay in milliseconds between repeat operations (default: 0)
+- `-r, --repeat <count>` - Execute multiple buys in sequence (stops early if token graduates or insufficient funds)
+- `-d, --delay <ms>` - Delay in milliseconds between repeat operations (default: 0)
 
 **Examples with repeat:**
 
 ```bash
 # Execute 10 buys back-to-back
-httpcat buy MTK 0.10 --repeat 10
+httpcat buy MTK 0.10 -r 10
 
 # Execute 10 buys with 500ms delay between each
-httpcat buy MTK 0.10 --repeat 10 --delay 500
+httpcat buy MTK 0.10 -r 10 -d 500
 ```
 
 **Token Identifier:**
 
-You can use any of the following formats:
-- **Contract address** (recommended): `0x1234567890123456789012345678901234567890`
-- **Token ID (UUID)**: `abc123-4567-89ab-cdef-0123456789ab`
-- **Token name**: `"My Token"` (use quotes if it contains spaces)
-- **Token symbol**: `MTK` (case-insensitive)
-
-**Note:** If multiple tokens share the same name or symbol, the system will automatically select the token with the highest graduation progress. For buy/sell operations, it's recommended to use the contract address for unambiguous identification.
+- Token address: `0x1234...` (contract address)
+- Token name: `"My Token"` (use quotes if it contains spaces)
+- Token symbol: `MTK` (case-insensitive)
 
 **Amounts:**
 
@@ -259,7 +251,8 @@ You can use any of the following formats:
 
 **Repeat Mode Behavior:**
 
-When using `--repeat`, the command will:
+When using `-r, --repeat`, the command will:
+
 - Execute the specified number of buys sequentially
 - Stop early if the token graduates (reaches 100% graduation progress)
 - Stop early if you run out of funds (HTTP 402 error)
@@ -273,8 +266,7 @@ Sell tokens back to the bonding curve.
 **Interactive:**
 
 ```bash
-httpcat> sell 0x1234567890123456789012345678901234567890 1000  # Sell 1000 tokens
-httpcat> sell abc123-... 1000        # Sell 1000 tokens
+httpcat> sell 0x1234... 1000        # Sell 1000 tokens
 httpcat> sell "My Token" 50%         # Sell 50% of holdings
 httpcat> sell MTK all                # Sell all tokens
 ```
@@ -282,15 +274,14 @@ httpcat> sell MTK all                # Sell all tokens
 **CLI:**
 
 ```bash
-httpcat sell 0x1234567890123456789012345678901234567890 1000
-httpcat sell abc123-4567-89ab-cdef-0123456789ab 1000
+httpcat sell 0x1234567890abcdef1234567890abcdef12345678 1000
 httpcat sell "My Token" 50%
 httpcat sell MTK all
 ```
 
 **Token Identifier:**
 
-- Contract address, Token ID (UUID), name, or symbol (same as buy command)
+- Address, name, or symbol (same as buy command)
 
 **Cost:** Dynamic based on amount (1% fee deducted from proceeds)
 
@@ -301,8 +292,7 @@ Get detailed information about a token.
 **Interactive:**
 
 ```bash
-httpcat> info 0x1234567890123456789012345678901234567890
-httpcat> info abc123-...
+httpcat> info 0x1234...
 httpcat> info "My Token"
 httpcat> info MTK
 ```
@@ -310,26 +300,23 @@ httpcat> info MTK
 **CLI:**
 
 ```bash
-httpcat info 0x1234567890123456789012345678901234567890
-httpcat info abc123-4567-89ab-cdef-0123456789ab
+httpcat info 0x1234567890abcdef1234567890abcdef12345678
 httpcat info "My Token"
 httpcat info MTK
 ```
 
 **Token Identifier:**
 
-- Contract address, Token ID (UUID), name, or symbol (same as buy command)
+- Address, name, or symbol (same as buy command)
 
 **Output:**
 
-- Token name, symbol, and contract address
+- Token name, symbol, address
 - Current price and market cap
 - Graduation progress
 - Your position (if you hold any)
 - P&L calculation
 
-**Note:** The token list now prominently displays contract addresses, making it easy to copy and use addresses for commands.
-
 **Cost:** $0.0001 USDC
 
 ### List Tokens
@@ -354,9 +341,9 @@ httpcat list --page 3 --sort name
 
 **Options:**
 
-- `--sort <field>` - Sort by `mcap`, `created`, or `name` (default: `mcap`)
-- `--limit <n>` - Items per page (default: 20, max: 100)
-- `--page <n>` - Page number (default: 1)
+- `-s, --sort <field>` - Sort by `mcap`, `created`, or `name` (default: `mcap`)
+- `-l, --limit <n>` - Items per page (default: 20, max: 100)
+- `-p, --page <n>` - Page number (default: 1)
 
 **Cost:** $0.0001 USDC
 
@@ -374,13 +361,14 @@ httpcat> positions
 
 ```bash
 httpcat positions
-httpcat --json positions
-httpcat --private-key 0x... positions
+httpcat -j positions
+httpcat -k 0x... positions
 ```
 
 **Output:**
 
 For each position:
+
 - Token information (name, symbol, address, status, price, market cap, graduation progress)
 - Position details (tokens owned, USDC invested, current value, average cost per token)
 - Performance metrics (profit/loss in USDC and percentage ROI)
@@ -389,6 +377,7 @@ For each position:
 - Timestamps (position created and updated dates)
 
 Portfolio summary:
+
 - Total positions count
 - Total portfolio value
 - Total amount invested
@@ -396,21 +385,21 @@ Portfolio summary:
 
 **Cost:** $0.01 USDC
 
-### Check Balance
+### Check Balances
 
 Check your wallet's ETH and USDC balances.
 
 **Interactive:**
 
 ```bash
-httpcat> balance
+httpcat> balances
 ```
 
 **CLI:**
 
 ```bash
-httpcat balance
-httpcat balance --private-key 0x...
+httpcat balances
+httpcat balances -k 0x...
 ```
 
 **Output:**
@@ -462,21 +451,19 @@ httpcat chat
 httpcat chat MTK
 httpcat chat "My Token"
 httpcat chat 0x1234...
-httpcat --json chat MTK
-httpcat --json --input-format stream-json chat MTK  # Structured JSON input
+httpcat -j chat MTK
+httpcat -j -f stream-json chat MTK  # Structured JSON input
 ```
 
 **Token Identifier:**
 
-You can use any of the following formats:
-- **Contract address** (recommended): `0x1234567890123456789012345678901234567890`
-- **Token symbol**: `MTK` (case-insensitive)
-- **Token name**: `"My Token"` (use quotes if it contains spaces)
-- **Token ID (UUID)**: `abc123-4567-89ab-cdef-0123456789ab`
+- Token symbol: `MTK` (case-insensitive)
+- Token name: `"My Token"` (use quotes if it contains spaces)
+- Token address: `0x1234...`
 
 **Options:**
 
-- `--input-format <format>` - Input format (only works with `--json`): `"text"` (default) or `"stream-json"` (realtime streaming input)
+- `-f, --input-format <format>` - Input format (only works with `--json`): `"text"` (default) or `"stream-json"` (realtime streaming input)
   - `"text"`: Line-delimited text input (default)
   - `"stream-json"`: Newline-delimited JSON (NDJSON) objects. Each line is a JSON object: `{"message": "text"}` or `{"command": "/renew"}`
 
@@ -484,6 +471,20 @@ You can use any of the following formats:
 
 **Note:** For AI agents, consider using MCP tools (`chat_join`, `chat_send_message`, etc.) instead of CLI streaming for better integration. See [MCP Chat Tools](#chat-tools-usage-example) section.
 
+### Help
+
+Display help information for httpcat.
+
+**CLI:**
+
+```bash
+httpcat help
+httpcat --help
+httpcat -h
+```
+
+All three commands show the same help output with available commands and options.
+
 ### Configuration
 
 Manage your httpcat configuration.
@@ -491,17 +492,17 @@ Manage your httpcat configuration.
 **Interactive:**
 
 ```bash
-httpcat> config --show              # Show current config
-httpcat> config --set network=base  # Update a setting
-httpcat> config --reset             # Re-run setup wizard
+httpcat> config -s              # Show current config
+httpcat> config -S network=base  # Update a setting
+httpcat> config -r             # Re-run setup wizard
 ```
 
 **CLI:**
 
 ```bash
 httpcat config                    # Run setup wizard
-httpcat config --show             # Show current config (JSON)
-httpcat config --set network=base # Update a setting
+httpcat config -s             # Show current config (JSON)
+httpcat config -S network=base # Update a setting
 ```
 
 ### MCP Server
@@ -544,10 +545,10 @@ Perfect for scripting, automation, or LLM/agent integration.
 
 ### JSON Output
 
-Add `--json` flag to any command:
+Add `-j, --json` flag to any command:
 
 ```bash
-$ httpcat --json create "Test Token" "TEST"
+$ httpcat -j create "Test Token" "TEST"
 {
   "success": true,
   "operation": "create_token",
@@ -754,7 +755,7 @@ All commands with `--json` flag return structured JSON responses. The output fol
 }
 ```
 
-**Balance (`balance`)**
+**Balances (`balances`)**
 
 ```json
 {
@@ -780,7 +781,7 @@ All commands with `--json` flag return structured JSON responses. The output fol
 Minimal output, only exit codes:
 
 ```bash
-$ httpcat --quiet buy abc123-... 0.20
+$ httpcat -q buy abc123-... 0.20
 $ echo $?
 0
 ```
@@ -800,21 +801,21 @@ $ echo $?
 #!/bin/bash
 
 # Create a token
-RESULT=$(httpcat --json create "AI Token" "AI")
-TOKEN_ID=$(echo $RESULT | jq -r '.data.tokenId')
+RESULT=$(httpcat -j create "AI Token" "AI")
+TOKEN_ADDRESS=$(echo $RESULT | jq -r '.data.tokenAddress')
 
 # Buy some tokens
-httpcat --json buy $TOKEN_ID 5
+httpcat -j buy $TOKEN_ADDRESS 5
 
 # Get current info
-httpcat --json info $TOKEN_ID
+httpcat -j info $TOKEN_ADDRESS
 
 # Sell 50% if profitable
-INFO=$(httpcat --json info $TOKEN_ID)
+INFO=$(httpcat -j info $TOKEN_ADDRESS)
 PNL=$(echo $INFO | jq -r '.data.userPosition.pnl')
 
 if (( $(echo "$PNL > 0" | bc -l) )); then
-  httpcat --json sell $TOKEN_ID 50%
+  httpcat -j sell $TOKEN_ADDRESS 50%
 fi
 ```
 
@@ -824,11 +825,11 @@ For scripts that need raw streaming access:
 
 ```bash
 # Using stream-json input format
-echo '{"message": "Hello!"}' | httpcat --json --input-format stream-json chat MTK
-echo '{"command": "/renew"}' | httpcat --json --input-format stream-json chat MTK
+echo '{"message": "Hello!"}' | httpcat -j -f stream-json chat MTK
+echo '{"command": "/renew"}' | httpcat -j -f stream-json chat MTK
 
 # Or pipe multiple messages
-cat messages.ndjson | httpcat --json --input-format stream-json chat MTK
+cat messages.ndjson | httpcat -j -f stream-json chat MTK
 ```
 
 **Note:** For AI agents, MCP tools are recommended over CLI streaming. See [MCP Chat Tools](#chat-tools-usage-example) section.
@@ -934,7 +935,7 @@ Buy tokens from the bonding curve.
 
 **Parameters:**
 
-- `identifier` (string, required) - Token identifier: contract address (0x...), UUID, name, or symbol
+- `identifier` (string, required) - Address, name, or symbol
 - `amount` (string, required) - Amount: "0.05", "0.10", or "0.20" (testnet) | "50", "100", or "200" (mainnet)
 - `privateKey` (string, optional) - Private key (overrides config/env)
 
@@ -946,7 +947,7 @@ Sell tokens back to the bonding curve.
 
 **Parameters:**
 
-- `identifier` (string, required) - Token identifier: contract address (0x...), UUID, name, or symbol
+- `identifier` (string, required) - Address, name, or symbol
 - `amount` (string, required) - Amount: number (e.g., "1000"), percentage (e.g., "50%"), or "all"
 - `privateKey` (string, optional) - Private key (overrides config/env)
 
@@ -958,7 +959,7 @@ Get detailed information about a token.
 
 **Parameters:**
 
-- `identifier` (string, required) - Token identifier: contract address (0x...), UUID, name, or symbol
+- `identifier` (string, required) - Address, name, or symbol
 - `privateKey` (string, optional) - Private key (overrides config/env)
 
 **Returns:** Token details, price, market cap, graduation progress, and your position (if you own tokens)
@@ -987,6 +988,7 @@ Get all your positions with comprehensive information including current value, p
 - `privateKey` (string, optional) - Private key (overrides config/env)
 
 **Returns:** All positions for the requesting address with:
+
 - Position details (tokens owned, USDC invested, current value, average cost)
 - Performance metrics (profit/loss, ROI percentage)
 - Position age and transaction history
@@ -1079,33 +1081,34 @@ Here's how an AI agent like Claude Code would use the chat tools:
 
 ```javascript
 // Step 1: Join the FRIDA token chat room
-const joinResult = await mcp.callTool("chat_join", { 
-  tokenIdentifier: "FRIDA" 
+const joinResult = await mcp.callTool("chat_join", {
+  tokenIdentifier: "FRIDA",
 });
 // Returns: { leaseId: "abc123...", leaseExpiresAt: "...", lastMessages: [...] }
 
 // Step 2: Send a message
 const sendResult = await mcp.callTool("chat_send_message", {
   message: "Hello FRIDA community!",
-  leaseId: joinResult.leaseId
+  leaseId: joinResult.leaseId,
 });
 // Returns: { messageId: "msg456...", timestamp: "...", message: "...", author: "0x..." }
 
 // Step 3: Poll for new messages (agent does this periodically)
 const messages = await mcp.callTool("chat_get_recent_messages", {
   leaseId: joinResult.leaseId,
-  limit: 20
+  limit: 20,
 });
 // Returns: { messages: [...] }
 
 // Step 4: Renew lease when needed
 const renewal = await mcp.callTool("chat_renew_lease", {
-  leaseId: joinResult.leaseId
+  leaseId: joinResult.leaseId,
 });
 // Returns: { leaseId: "new-lease-id...", leaseExpiresAt: "..." }
 ```
 
 **Key Benefits:**
+
 - No shell scripting or process management required
 - WebSocket connections maintained automatically by MCP server
 - Messages cached in memory for quick retrieval
@@ -1127,9 +1130,8 @@ Once configured, AI assistants can use the tools like this:
 
 ```
 create_token(name="Moon Token", symbol="MOON", websiteUrl="https://moon.com")
-buy_token(identifier="0x1234567890123456789012345678901234567890", amount="0.20")
-buy_token(identifier="MOON", amount="0.20")  # Can also use symbol
-token_info(identifier="0x1234567890123456789012345678901234567890")
+buy_token(identifier="0x1234...", amount="0.20")
+token_info(identifier="MOON")
 list_tokens(sort="mcap", limit=10)
 check_balance()
 ```
@@ -1206,7 +1208,7 @@ httpcat env show
 
 ```bash
 # Add a custom environment
-httpcat env add production http://production-agent:8787 --network base
+httpcat env add production http://production-agent:8787 -n base
 
 # Switch to it
 httpcat env use production
@@ -1247,8 +1249,8 @@ You can also pass the private key directly via command-line flag (highest priori
 
 ```bash
 # Private key priority: CLI flag > Environment variable > Config file
-httpcat --private-key 0x1234567890abcdef... create "My Token" "MTK"
-httpcat --private-key 0x1234567890abcdef... --json buy abc123-... 0.20
+httpcat -k 0x1234567890abcdef... create "My Token" "MTK"
+httpcat -k 0x1234567890abcdef... -j buy 0x1234... 0.20
 ```
 
 **Note:** The `--private-key` flag takes precedence over environment variables and config file settings.
@@ -1257,8 +1259,8 @@ httpcat --private-key 0x1234567890abcdef... --json buy abc123-... 0.20
 
 ```bash
 # Switch to mainnet
-httpcat config --set network=base
-httpcat config --set agentUrl=http://production-url:8787
+httpcat config -S network=base
+httpcat config -S agentUrl=http://production-url:8787
 
 # Or in interactive mode
 httpcat> network base
@@ -1373,10 +1375,10 @@ httpcat config --show
 
 ### Check Wallet Balance
 
-Use the balance command to check your wallet's ETH and USDC balances:
+Use the balances command to check your wallet's ETH and USDC balances:
 
 ```bash
-httpcat balance
+httpcat balances
 ```
 
 This will show your wallet address, ETH balance (for gas fees), and USDC balance (for trading), with warnings if balances are low.
@@ -1389,28 +1391,25 @@ This will show your wallet address, ETH balance (for gas fees), and USDC balance
 # Setup
 httpcat config
 
-# Check your wallet balance
-httpcat balance
+# Check your wallet balances
+httpcat balances
 
 # Create a token
-httpcat create "Moon Cat" "MOON" --website https://mooncat.io
+httpcat create "Moon Cat" "MOON" -w --website https://mooncat.io
 
-# Buy tokens (using contract address, UUID, name, or symbol)
-httpcat buy 0x1234567890123456789012345678901234567890 0.20
-httpcat buy <tokenId> 0.20
-httpcat buy "My Token" 0.20
-httpcat buy MTK 0.20
+# Buy tokens
+httpcat buy 0x1234... 5
 
 # Check your position
-httpcat info 0x1234567890123456789012345678901234567890
+httpcat info 0x1234...
 
 # Get all your positions with comprehensive info
 httpcat positions
 
 # Sell half when profitable
-httpcat sell 0x1234567890123456789012345678901234567890 50%
+httpcat sell 0x1234... 50%
 
-# List all your tokens (shows positions and addresses)
+# List all your tokens (shows positions)
 httpcat list
 ```
 
@@ -1419,16 +1418,16 @@ httpcat list
 ```bash
 #!/bin/bash
 
-TOKEN_ID="abc123-..."
+TOKEN_ADDRESS="0x1234567890abcdef1234567890abcdef12345678"
 
 # Monitor and trade
 while true; do
-  INFO=$(httpcat --json info $TOKEN_ID)
+  INFO=$(httpcat -j info $TOKEN_ADDRESS)
   PROGRESS=$(echo $INFO | jq -r '.data.graduationProgress')
 
   # Buy if close to graduation
   if (( $(echo "$PROGRESS > 90" | bc -l) )); then
-    httpcat --quiet buy $TOKEN_ID 5
+    httpcat -q buy $TOKEN_ADDRESS 5
   fi
 
   sleep 60