npm package: @predictengine/cli
Description: PredictEngine institutional trading CLI
Author: PredictEngine
Latest version: 1.0.1

# @predictengine/cli

Command-line interface for PredictEngine's institutional trading API. Trade prediction markets, monitor positions, track whales, and more — all from your terminal.

## Installation

```bash
# Install globally from npm
npm install -g @predictengine/cli

# Or install from source
git clone https://github.com/imblocksavvy-spec/predictengine-frontend.git
cd predictengine-frontend/cli
npm install
npm run build
npm link
```

## Quick Start

```bash
# 1. Configure your API credentials
pe config

# 2. Check API health
pe health

# 3. Browse markets
pe markets --limit 10

# 4. Place a trade
pe order buy --token <TOKEN_ID> --price 0.55 --size 100
```

## Configuration

Credentials are stored in `~/.predictengine/config.json` (permissions: 600).

### Interactive Setup

```bash
pe config
```

### With Flags

```bash
pe config --key YOUR_API_KEY --secret YOUR_API_SECRET
```

### Environment Variables

You can also set credentials via environment variables (these take precedence over the config file):

```bash
export PE_API_KEY=your_api_key
export PE_API_SECRET=your_api_secret
```

### View Current Config

```bash
pe config --show
```

## Commands

### Market Data

```bash
# List markets
pe markets
pe markets --limit 50 --category crypto
pe markets --search "bitcoin" --active

# Market details
pe market <MARKET_ID>

# L2 orderbook
pe orderbook <TOKEN_ID>

# Price movers
pe movers

# Volume leaders
pe volume
```

### Trading

```bash
# Place buy order
pe order buy --token <TOKEN_ID> --price 0.55 --size 100
pe order buy --token <TOKEN_ID> --price 0.55 --size 100 --type market

# Place sell order
pe order sell --token <TOKEN_ID> --price 0.75 --size 50

# Cancel order
pe order cancel <ORDER_ID>

# List open orders
pe orders
pe orders --status pending --market <MARKET_ID>
```

### Portfolio

```bash
# Portfolio summary (balance, exposure, P&L)
pe portfolio

# Open positions
pe positions
pe positions --status open

# P&L breakdown
pe pnl
pe pnl --group-by day
pe pnl --group-by month

# Trade history
pe trades --limit 100
pe trades --export csv
```

### Intelligence

```bash
# Whale alerts
pe whales --limit 20

# Market news
pe news --limit 10 --category crypto

# Fee schedule
pe fees
```

### System

```bash
# API health check
pe health

# Show help
pe --help
pe order --help
```

### JSON Output

Every command supports the `--json` flag for raw JSON output, useful for scripting:

```bash
pe markets --json | jq '.markets[0]'
pe positions --json > positions.json
pe portfolio --json | jq '.total_pnl'
```

## Authentication

The CLI uses HMAC-SHA256 signed requests. Each request includes:

- `X-PE-API-KEY` — Your API key
- `X-PE-TIMESTAMP` — Unix timestamp
- `X-PE-SIGNATURE` — HMAC-SHA256 of `{timestamp}{method}{path}{body}`

Public endpoints (markets, orderbook, movers, volume, news, whales, health) work without authentication. Trading endpoints (orders, positions, portfolio, pnl, trades, fees) require valid credentials.

## Examples

### Monitor a Market

```bash
# Watch orderbook for a token
watch -n 5 'pe orderbook <TOKEN_ID> --json | jq "{best_bid: .bids[0], best_ask: .asks[0]}"'
```

### Export Daily Trades

```bash
pe trades --limit 1000 --export csv
```

### Quick Portfolio Check

```bash
pe portfolio && pe positions
```

### Scripting with JSON Output

```bash
# Get total P&L
TOTAL_PNL=$(pe portfolio --json | jq -r '.total_pnl')
echo "Total P&L: $TOTAL_PNL"

# Count open positions
OPEN=$(pe positions --json | jq '.positions | length')
echo "Open positions: $OPEN"
```

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev -- markets --limit 5

# Build
npm run build

# Run built version
npm start -- health
```

## Requirements

- Node.js >= 18.0.0
- PredictEngine API credentials (get them at https://predictengine.ai/dashboard/settings)

## API Base URL

Default: `https://api.predictengine.ai/api/v2`

Override via config or environment variable:

```bash
pe config --url https://custom-api-url.com/api/v2
# or
export PE_BASE_URL=https://custom-api-url.com/api/v2
```

## License

MIT