hufi-cli 0.5.5 → 0.8.1

package/README.md

@@ -1,82 +1,187 @@
 # hufi-cli
 
-CLI tool for the hu.fi DeFi platform.
+CLI tool for the [hu.fi](https://hu.finance) DeFi platform.
 
 ## Install
 
 ```bash
-bun install
+bun install -g hufi-cli
 ```
 
-## Usage
+Or run without installing:
 
 ```bash
-# Show help
-bunx hufi-cli --help
+bunx hufi-cli <command>
+```
 
-# Generate a new wallet (key saved to ~/.hufi-cli/key.json)
-bunx hufi-cli auth generate
+All examples below assume global install. Otherwise replace `hufi` with `bunx hufi-cli`.
 
-# Authenticate (uses saved key by default)
-bunx hufi-cli auth login
+## Quick Start
 
-# Check auth status
-bunx hufi-cli auth status
+```bash
+# Generate a wallet
+hufi auth generate
 
-# Register exchange API key
-bunx hufi-cli exchange register --name mexc --api-key xxx --secret-key yyy
+# Login with saved key
+hufi auth login
 
-# List exchange API keys
-bunx hufi-cli exchange list
+# Browse campaigns
+hufi campaign list
+```
 
-# Check campaign join status
-bunx hufi-cli campaign status --chain-id 137 --address 0x...
+## Commands
 
-# Join a campaign
-bunx hufi-cli campaign join --chain-id 137 --address 0x...
+### auth
 
-# List joined campaigns
-bunx hufi-cli campaign list --limit 20
+| Command | Description |
+|---------|-------------|
+| `auth generate` | Generate a new EVM wallet (saves to `~/.hufi-cli/key.json`) |
+| `auth login` | Authenticate with Recording Oracle (uses saved key by default) |
+| `auth status` | Show current auth status |
+
+```bash
+hufi auth generate --json
+hufi auth login --private-key <key>
+hufi auth status
 ```
 
-## Global Options
+### campaign
 
-- `--json` - Output as JSON (available on all commands)
+| Command | Description |
+|---------|-------------|
+| `campaign list` | Browse available campaigns |
+| `campaign get` | Get details for a specific campaign |
+| `campaign joined` | List campaigns you've joined |
+| `campaign join` | Join a campaign |
+| `campaign status` | Check join status |
+| `campaign progress` | Check your progress |
+| `campaign leaderboard` | View campaign leaderboard |
+| `campaign create` | Create a new campaign (launch escrow on-chain) |
 
-## Configuration
+```bash
+hufi campaign list                                          # list active campaigns
+hufi campaign list --status completed --chain-id 1          # completed on Ethereum
+hufi campaign get --chain-id 137 --address 0x...            # campaign details
+hufi campaign join --address 0x...                          # join (chain-id defaults to 137)
+hufi campaign status --address 0x...                        # check status
+hufi campaign progress --address 0x...                      # your progress
+hufi campaign leaderboard --address 0x...                   # leaderboard
+```
 
-Configuration is stored at `~/.hufi-cli/config.json`.
+#### Campaign Create
 
-## Capabilities
+Requires staked HMT, gas, and fund tokens (USDT/USDC). Creates an escrow contract on-chain.
 
-### What This CLI Can Do
+```bash
+# Market Making
+hufi campaign create \
+  --type market_making --exchange mexc --symbol HMT/USDT \
+  --start-date 2026-04-01 --end-date 2026-05-01 \
+  --fund-token USDT --fund-amount 10000 \
+  --daily-volume-target 50000
+
+# Holding
+hufi campaign create \
+  --type holding --exchange mexc --symbol HMT \
+  --start-date 2026-04-01 --end-date 2026-05-01 \
+  --fund-token USDT --fund-amount 5000 \
+  --daily-balance-target 1000
+
+# Threshold
+hufi campaign create \
+  --type threshold --exchange mexc --symbol HMT \
+  --start-date 2026-04-01 --end-date 2026-05-01 \
+  --fund-token USDT --fund-amount 5000 \
+  --minimum-balance-target 500
+```
 
-| Module | Commands | Description |
-|--------|----------|-------------|
-| **auth** | login, generate, status | Authentication & wallet management |
-| **exchange** | register, list | Exchange API key management |
-| **campaign** | list, get, joined, join, status, progress, leaderboard | Campaign browsing, joining, and monitoring |
+Running `campaign status/join/progress/leaderboard` without `-a` shows help.
 
-### What This CLI Cannot Do
+### exchange
 
-- ❌ Execute on-chain transactions
-- ❌ Configure trading strategies
-- ❌ Multi-signature or voting operations
+| Command | Description |
+|---------|-------------|
+| `exchange register` | Register a read-only exchange API key |
+| `exchange list` | List registered API keys |
+| `exchange delete` | Delete API keys for an exchange |
+| `exchange revalidate` | Revalidate an exchange API key |
 
-## API Endpoints
+```bash
+hufi exchange register --name mexc --api-key <key> --secret-key <secret>
+hufi exchange list
+hufi exchange revalidate --name mexc
+hufi exchange delete --name mexc
+```
 
-- Recording Oracle: `https://ro.hu.finance`
-- Campaign Launcher: `https://cl.hu.finance`
+### staking
 
-## Development
+| Command | Description |
+|---------|-------------|
+| `staking status` | Check HMT staking status |
+| `staking deposit` | Show deposit address and QR code |
+| `staking stake` | Stake HMT tokens |
+| `staking unstake` | Initiate unstaking (tokens locked for lock period) |
+| `staking withdraw` | Withdraw unlocked tokens after lock period |
+
+```bash
+hufi staking deposit                                   # show address QR code
+hufi staking status                                    # check your staking
+hufi staking status --address 0x...                    # check another address
+hufi staking stake -a 1000                             # stake 1000 HMT
+hufi staking unstake -a 500                            # unstake 500 HMT
+hufi staking withdraw                                  # withdraw unlocked tokens
+```
+
+Supports Polygon (chain 137) and Ethereum (chain 1). Staking contract: `0x01D1...07F1D` on Polygon.
+
+### dashboard
+
+Portfolio overview — staking, active campaigns, and progress in one view.
 
 ```bash
-# Run directly
-bunx hufi-cli --help
+hufi dashboard              # full overview
+hufi dashboard --json       # machine output
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--config-file <path>` | Custom config file (default: `~/.hufi-cli/config.json`) |
+| `--key-file <path>` | Custom key file (default: `~/.hufi-cli/key.json`) |
+| `-V, --version` | Show version |
+| `-h, --help` | Show help |
+
+All commands support `--json` for machine-readable output.
+
+## Configuration
 
-# Run tests
-bun test
+Stored at `~/.hufi-cli/config.json`:
 
-# Type check
-bun run typecheck
+```json
+{
+  "recordingApiUrl": "https://ro.hu.finance",
+  "launcherApiUrl": "https://cl.hu.finance",
+  "defaultChainId": 137,
+  "address": "0x...",
+  "accessToken": "..."
+}
 ```
+
+## Development
+
+```bash
+bun install              # install deps
+bun run dev -- --help    # run from source
+bun run build            # build to dist/cli.js
+bun test                 # unit tests
+bun run test:cli         # integration tests
+bun run typecheck        # type check
+```
+
+## API Endpoints
+
+| Service | URL |
+|---------|-----|
+| Recording Oracle | https://ro.hu.finance |
+| Campaign Launcher | https://cl.hu.finance |