Wooo Cli

wooo-cli Usage Guide

wooo-cli is a terminal-native crypto CLI that unifies CEX trading, DEX swaps, DeFi lending, staking, perps, prediction markets, cross-chain bridges, and on-chain utilities into a single tool with consistent flags, structured output, and built-in wallet management.

The CLI binary is wooo-cli (not wooo). Always use the full name.

Core Philosophy

wooo-cli treats real money the same way a gun treats bullets — every command that moves funds has a safety mechanism. Your job is to keep that safety on until the user is ready to fire.

The Safety Checklist (follow for every write operation):

1. Verify prerequisites — Is the wallet set up? Are API keys configured? Is there enough balance?
2. Dry-run first — Always run with --dry-run before executing. This shows the full execution plan without spending anything.
3. Confirm chain and amounts — Read back what will happen: "This will swap 1 ETH for ~3,200 USDC on Arbitrum. Gas estimated at ~$0.03."
4. Let the user confirm — Never add --yes unless the user explicitly asks for unattended execution.
5. Execute — Only after the user reviews and approves.

Read-only commands (price, balance, positions, markets) are always safe and don't need this ceremony.

---

Command Structure

wooo-cli [global-flags]    [args]

Universal commands are top-level: config, wallet, market, portfolio, chain, swap.

Protocol commands are grouped by type:

| Group | Protocols | Actions | |-------|-----------|---------| | cex | okx, binance, bybit | buy, sell, long, short, balance, positions | | dex | uniswap, curve, jupiter | swap, quote, tokens/pools | | lend | aave, morpho | markets, supply, withdraw, borrow, repay, positions, rates | | stake | lido | stake, balance, rewards | | perps | hyperliquid | long, short, positions, funding | | prediction | polymarket | markets, events, clob, approve, and CLOB trading | | bridge | lifi, okx | bridge, quote, status, chains | | pay | mpp, x402 | machine payment protocols |

---

Global Flags

Available on every command:

| Flag | Purpose | |------|---------| | --json | Force JSON output (useful for piping or automation) | | --format table\|json\|csv | Choose output format | | --chain | Target chain (see Chain Support below) | | --wallet | Use a specific wallet instead of the active one | | --yes | Skip confirmation prompts — use with caution | | --dry-run | Preview execution plan without sending transactions | | --verbose | Show debug output | | --quiet | Suppress non-essential output |

---

Chain Support

| Chain | Canonical Name | Aliases | |-------|---------------|---------| | Ethereum | ethereum | eth, mainnet | | Arbitrum | arbitrum | arb | | Optimism | optimism | op | | Polygon | polygon | matic, poly | | Base | base | — | | BSC | bsc | — | | Avalanche | avalanche | — | | Solana | solana | sol |

EVM protocols (Uniswap, Curve, Aave, Morpho, Lido, bridges) work on EVM chains only. Jupiter is Solana-only (no --chain flag needed). Aggregated swap (wooo-cli swap) auto-routes to the right DEX based on chain — uses Jupiter for Solana, Uniswap/Curve for EVM.

Validation Policy

For external testing, default to the mainnet-fork Anvil E2E flow rather than testnets. This repo treats fork-backed validation as the authoritative way to verify protocol addresses, token manifests, and execution paths without risking real funds.

If you are acting as an agent:

1. Prefer bun run test:e2e:anvil when validating on-chain changes.
2. Assume mainnet addresses are the source of truth unless the repo explicitly says otherwise.
3. Do not present testnet support as a guarantee unless the CLI docs say so.
4. If a change touches protocol constants or routing, make sure fork-backed E2E coverage exists.

---

Setup & Configuration

First-Time Setup

npm install -g wooo-cli
wooo-cli config init
wooo-cli wallet create my-wallet      # prompts for passphrase

Or import an existing key:

wooo-cli wallet import my-key 0xprivatekey...
wooo-cli wallet import my-mnemonic --mnemonic   # interactive prompt
wooo-cli wallet import from-file --file /path/to/keyfile

For non-interactive / automation:

wooo-cli secret set ows/passphrase

wooo-cli secret set ows/api-key

CEX API Keys

Required for any wooo-cli cex commands. Use auth for the normal flow:

wooo-cli auth set okx
wooo-cli auth set binance
wooo-cli auth set bybit

Advanced secret-ref overrides:

wooo-cli config set okx.apiKeyRef keychain:okx/api-key
wooo-cli config set okx.apiSecretRef keychain:okx/api-secret
wooo-cli config set okx.passphraseRef keychain:okx/passphrase

OKX Onchain / Web3 / DEX API (separate credentials)

Required for market okx, portfolio okx, chain okx, and OKX bridge/DEX commands. These credentials come from the OKX Web3 Developer Portal and are separate from OKX Exchange keys:

wooo-cli auth set okx-onchain --project-id 

---

Complete Command Reference

Wallet Management

wooo-cli wallet create  [--words 12|24]
wooo-cli wallet import  [key] [--mnemonic] [--file ] [--chain evm|solana]
wooo-cli wallet export  --confirm
wooo-cli wallet list
wooo-cli wallet info 
wooo-cli wallet switch 
wooo-cli wallet delete  --confirm
wooo-cli wallet balance [address] [--chain ]

Remote / hardware wallets:

wooo-cli wallet discover --signer http://127.0.0.1:8787/
wooo-cli wallet connect  --signer  [--address ] [--auth-ref ]
wooo-cli wallet disconnect 

Wallet custody mode is explicit and does not fall back between local and remote custody. The default is local-only. Set WOOO_WALLET_MODE=remote to use connected remote accounts; resolution will fail instead of using a local wallet. Use WOOO_WALLET_MODE=local or leave it unset for local-only custody.

Policy & API key management:

wooo-cli wallet policy create 
wooo-cli wallet policy list
wooo-cli wallet policy show 
wooo-cli wallet policy delete 
wooo-cli wallet key create  --wallet  --policy 
wooo-cli wallet key list
wooo-cli wallet key revoke 

Market Data (read-only, always safe)

wooo-cli market price               # e.g. BTC, ETH/USDT
wooo-cli market search             # e.g. DOGE
wooo-cli market search  --exchange binance

OKX Onchain data (requires OKX Onchain API credentials):

wooo-cli market okx chains
wooo-cli market okx search  --chains ethereum,base [--max 20]
wooo-cli market okx token  
wooo-cli market okx metrics  
wooo-cli market okx price  
wooo-cli market okx trades   [--limit 20]
wooo-cli market okx candles   [--bar 1m|5m|15m|1H|4H|1D]
wooo-cli market okx holders   [--tag whale]
wooo-cli market okx ranking --chains ethereum,base [--sort volume|change|market-cap] [--window 5m|1h|4h|24h]

# OKX Agent market intelligence (public)
wooo-cli market okx filter --instType SPOT|SWAP|FUTURES [--sortBy volUsd24h|oiUsd|fundingRate|last|chg24hPct|marketCapUsd|listTime]
wooo-cli market okx oi-history  [--bar 5m|15m|1H|4H|1D] [--limit 50]
wooo-cli market okx oi-change --instType SWAP|FUTURES [--bar 5m|15m|1H|4H|1D] [--sortBy oiDeltaPct|oiDeltaUsd|oiUsd|volUsd24h|last]

OKX news / sentiment radar (requires OKX API credentials):

wooo-cli news okx latest [--coins BTC,ETH] [--platform blockbeats] [--lang zh-CN|en-US] [--limit 10]
wooo-cli news okx important [--coins BTC,ETH] [--lang zh-CN|en-US] [--limit 10]
wooo-cli news okx by-coin --coins BTC,ETH [--importance high|low] [--platform blockbeats]
wooo-cli news okx search  [--coins BTC] [--sentiment bullish|bearish|neutral]
wooo-cli news okx by-sentiment --sentiment bullish|bearish|neutral [--coins BTC]
wooo-cli news okx detail 
wooo-cli news okx platforms
wooo-cli news okx coin-sentiment --coins BTC,ETH [--period 1h|4h|24h]
wooo-cli news okx coin-trend  [--period 1h|4h|24h] [--points 24]
wooo-cli news okx sentiment-rank [--period 1h|4h|24h] [--sortBy hot|bullish|bearish]

Token Swaps

Aggregated swap (auto-picks best DEX route):

wooo-cli swap    --chain  [--dry-run] [--yes]

# Examples:
wooo-cli swap ETH USDC 1 --chain arbitrum --dry-run
wooo-cli swap SOL USDC 10 --chain solana --dry-run

Direct DEX access:

# Uniswap V3 (EVM chains)
wooo-cli dex uniswap swap    --chain  [--dry-run]
wooo-cli dex uniswap quote    --chain 
wooo-cli dex uniswap tokens --chain 

# Curve (EVM chains, optimized for stablecoins)
wooo-cli dex curve swap    --chain  [--dry-run]
wooo-cli dex curve quote    --chain 
wooo-cli dex curve pools --chain 

# Jupiter (Solana only — no --chain flag)
wooo-cli dex jupiter swap    [--dry-run]
wooo-cli dex jupiter quote   
wooo-cli dex jupiter tokens

CEX Trading

Same pattern for all exchanges (okx, binance, bybit):

# Account
wooo-cli cex  balance
wooo-cli cex  positions

# Spot trading
wooo-cli cex  buy   [--dry-run]     # e.g. BTC/USDT 500
wooo-cli cex  sell   [--dry-run]    # e.g. ETH/USDT 0.5

# Futures
wooo-cli cex  long   [--leverage ] [--dry-run]
wooo-cli cex  short   [--leverage ] [--dry-run]

• `: Trading pair like BTC/USDT, ETH/USDC`
• ``: Amount in quote currency for buy, base currency for sell
• `: Futures symbol like BTC/USDT:USDT`
• ``: Position size in USD
• --leverage: Leverage multiplier (default: 1)

Lending — Aave V3

# Discovery (read-only)
wooo-cli lend aave markets --chain 
wooo-cli lend aave rates  --chain  --market 
wooo-cli lend aave positions --chain  --market 

# Write operations
wooo-cli lend aave supply   --chain  --market  [--dry-run]
wooo-cli lend aave withdraw  [amount] [--all] --chain  --market  [--dry-run]
wooo-cli lend aave borrow   --chain  --market  [--dry-run]
wooo-cli lend aave repay  [amount] [--all] --chain  --market  [--dry-run]

Important: On chains with multiple Aave markets, --market is required for token-specific and position commands. Discover available markets first with wooo-cli lend aave markets --chain . The market name looks like AaveV3Ethereum — use it exactly.

Lending — Morpho Markets V1

# Discovery
wooo-cli lend morpho markets --chain  [--search ] [--loan-token ] [--collateral-token ] [--limit 10]
wooo-cli lend morpho market  --chain 
wooo-cli lend morpho positions --chain 

# Write operations (marketId is a 32-byte hex string like 0xb323...86cc)
wooo-cli lend morpho supply   --chain  [--dry-run]
wooo-cli lend morpho withdraw  [amount] [--all] --chain  [--dry-run]
wooo-cli lend morpho supply-collateral   --chain  [--dry-run]
wooo-cli lend morpho withdraw-collateral  [amount] [--all] --chain  [--dry-run]
wooo-cli lend morpho borrow   --chain  [--dry-run]
wooo-cli lend morpho repay  [amount] [--all] --chain  [--dry-run]

Staking — Lido

wooo-cli stake lido stake  [--dry-run]      # Stake ETH → stETH (Ethereum only)
wooo-cli stake lido balance                          # stETH balance
wooo-cli stake lido rewards                          # Staking rewards

Perpetual Futures — Hyperliquid

wooo-cli perps hyperliquid long   [--leverage ] [--dry-run]
wooo-cli perps hyperliquid short   [--leverage ] [--dry-run]
wooo-cli perps hyperliquid positions
wooo-cli perps hyperliquid funding

• `: Asset symbol like BTC, ETH`
• ``: Position size in USD
• --leverage: Leverage multiplier (default: 1)

Prediction Markets — Polymarket

wooo-cli prediction polymarket markets list [--limit 10]
wooo-cli prediction polymarket events get 
wooo-cli prediction polymarket clob ok                    # Check CLOB connectivity
wooo-cli prediction polymarket deposit supported-assets   # Official Bridge supported chains/tokens
wooo-cli prediction polymarket deposit addresses          # Official deposit addresses for configured deposit wallet
wooo-cli prediction polymarket deposit status    # Official deposit status
wooo-cli prediction polymarket deposit-wallet address     # Resolve configured deposit wallet
wooo-cli prediction polymarket deposit-wallet deploy [--dry-run]
wooo-cli prediction polymarket approve check              # Check deposit wallet approvals
wooo-cli prediction polymarket approve set [--dry-run]    # Set approvals through relayer WALLET batch
wooo-cli prediction polymarket clob create-order --token  --side buy --price 0.42 --size 10 [--dry-run]
wooo-cli prediction polymarket clob market-order --token  --side buy --amount 20 [--dry-run]

Polymarket trading uses deposit wallets and CLOB POLY_1271 signatures. The active signer comes from WOOO_WALLET_MODE; the target deposit wallet resolves from config polymarket.owner, config polymarket.depositWallet, --deposit-wallet, or, when no target is configured, the active signer as owner. If both owner and deposit wallet are provided, the deposit wallet must be the deterministic wallet for that owner. The CLI has no Polymarket session mode; owner/session authority belongs to the signer and Deposit Wallet contract. Deposit wallet deployment and approval writes go through the Polymarket relayer; use wooo-cli auth set polymarket-relayer and config polymarket.relayerApiKeyAddress for relayer authentication.

Cross-Chain Bridges

# LI.FI (EVM cross-chain aggregator)
wooo-cli bridge lifi bridge   --from-chain  --to-chain  [--to ] [--dry-run]
wooo-cli bridge lifi quote   --from-chain  --to-chain  [--to ]
wooo-cli bridge lifi status  --from-chain  --to-chain 
wooo-cli bridge lifi chains [--tokens]

# OKX Bridge
wooo-cli bridge okx bridge   --from-chain  --to-chain  [--to ] [--dry-run]
wooo-cli bridge okx quote   --from-chain  --to-chain  [--to ]
wooo-cli bridge okx status 
wooo-cli bridge okx chains [--tokens]

Bridge flags use --from-chain and --to-chain (not --chain). Both are EVM-only in this version.

On-Chain Utilities

wooo-cli chain tx  [--chain ]
wooo-cli chain balance  [--token ] [--chain ]
wooo-cli chain ens                               # ENS ↔ address (Ethereum only)
wooo-cli chain call   [args] [--chain ]

OKX Onchain history:

wooo-cli chain okx history  --chains ethereum,base [--token ] [--limit 20]
wooo-cli chain okx tx  

Portfolio

wooo-cli portfolio overview                    # Aggregated CEX balances

# OKX Onchain portfolio
wooo-cli portfolio okx chains
wooo-cli portfolio okx overview   [--window 1d|3d|7d|1m|3m]
wooo-cli portfolio okx value  --chains ethereum,base [--asset-type all|token|defi]
wooo-cli portfolio okx balances  --chains ethereum,base
wooo-cli portfolio okx balance   
wooo-cli portfolio okx recent-pnl   [--limit 20]
wooo-cli portfolio okx latest-pnl   
wooo-cli portfolio okx dex-history     [--type buy,sell]

Configuration

wooo-cli config init
wooo-cli config set  
wooo-cli config get 
wooo-cli config list

---

Decision Guide: What Command to Use

| User wants to... | Command | |-------------------|---------| | Check token price | wooo-cli market price | | Swap tokens (any chain) | wooo-cli swap --chain --dry-run | | Swap on specific DEX | wooo-cli dex swap ... | | Buy crypto on exchange | wooo-cli cex buy --dry-run | | Check exchange balance | wooo-cli cex balance | | Open leveraged long | wooo-cli perps hyperliquid long --leverage --dry-run | | Lend on Aave | wooo-cli lend aave supply --chain --market --dry-run | | Check DeFi positions | wooo-cli lend aave positions --chain --market | | Stake ETH | wooo-cli stake lido stake --dry-run | | Bridge tokens | wooo-cli bridge lifi bridge --from-chain --to-chain --dry-run | | Check wallet balance | wooo-cli wallet balance [--chain ] | | Check on-chain balance | wooo-cli chain balance --chain | | Look up ENS name | wooo-cli chain ens | | View portfolio PnL | wooo-cli portfolio okx overview --window 7d | | Find trending tokens | `wooo-cli market okx ranking --chains ethereu

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: daoleno
• Source: daoleno/wooo-cli
• License: MIT

Install and usage instructions live in the source repository linked above.