npm package: @predictions/cli
Description: Official CLI for the Synthesis prediction markets API
Author: Synthesis
Latest version: 1.0.0

# Synthesis CLI

Command-line interface for the [Synthesis](https://synthesis.trade) prediction markets platform. Browse markets, place orders, manage wallets, use real time data for agents, traders and builders.

## Install

```bash
# npm / pnpm
npm install -g @predictions/cli
pnpm add -g @predictions/cli

# Homebrew
brew install ryne-labs/cli
```

## Quick Start

```bash
# No auth needed — browse markets immediately
synthesis markets list
synthesis markets search "bitcoin"
synthesis pm get will-bitcoin-reach-100k

# JSON output for scripts and agents
synthesis -j markets list --limit 5
synthesis --output json wallet balance

# Set up auth and wallet interactively
synthesis setup
```

## Configuration

```bash
synthesis config set projectApiKey sk_...
synthesis config set defaultWallet wal_...
synthesis config set outputFormat json       # default: table
synthesis config list                        # show all config
synthesis config reset                       # reset to defaults
```

Config is stored at `~/.config/synthesis-cli/config.json`.

## Output Formats

Every command supports `--output table` (default) and `--output json`. Shorthand: `-j` for JSON.

```bash
# Human-readable table
synthesis markets list --limit 3

# Machine-readable JSON (for scripts, agents, LLMs)
synthesis -j markets list --limit 3

# Pipe to jq
synthesis -j markets search "election" | jq '.[].data'
```

**In JSON mode:**
- Success: `{"success": true, "data": ...}` on stdout
- Errors: `{"success": false, "error": "..."}` on stdout, non-zero exit code
- Spinners are suppressed

## Commands

### Markets

```bash
synthesis markets list                          # List trending markets
synthesis markets list --venue polymarket       # Filter by venue
synthesis markets list --live --sort volume     # Live markets by volume
synthesis markets search "bitcoin"              # Search markets
synthesis markets stats                         # Venue statistics
synthesis markets similar-pairs                 # Cross-venue arbitrage pairs
```

### Polymarket

```bash
synthesis pm list                               # List Polymarket markets
synthesis pm get will-bitcoin-reach-100k        # Get by slug
synthesis pm get 0xcondition_id                 # Get by condition ID
synthesis pm price <token_id>                   # Current price
synthesis pm orderbook <token_id>               # Orderbook depth
synthesis pm trades <condition_id>              # Recent trades
synthesis pm leaderboard                        # Top traders
```

### Kalshi

```bash
synthesis ka list                               # List Kalshi markets
synthesis ka get KXBTC-25                       # Get by event ID
synthesis ka leaderboard                        # Top traders
```

### Wallet

```bash
synthesis wallet list                           # List wallets
synthesis wallet create POL                     # Create Polygon wallet
synthesis wallet create SOL                     # Create Solana wallet
synthesis wallet delete <wallet_id>             # Delete a wallet
synthesis wallet balance                        # Check balance
synthesis wallet positions                      # View positions
synthesis wallet orders                         # View orders
synthesis wallet transfers                      # View transfers
synthesis wallet pnl                            # View PnL
synthesis wallet deposit                        # Get deposit address
```

Use `-w <wallet_id>` to specify a wallet, or set a default:

```bash
synthesis config set defaultWallet wal_abc123
```

### Trading

```bash
synthesis trade buy <token_id> 100              # Market buy $100
synthesis trade buy <token_id> 100 -p 0.65      # Limit buy at 65c
synthesis trade sell <token_id> 50              # Market sell $50
synthesis trade cancel <order_id>               # Cancel order
synthesis trade cancel-all                      # Cancel all orders
synthesis trade quote <token_id> 100            # Price quote

# Dry run — get quote without placing order
synthesis trade buy <token_id> 100 --dry-run
synthesis trade sell <token_id> 50 --dry-run

# Batch — place multiple orders at once
synthesis trade batch '[{"token_id":"...","side":"BUY","type":"MARKET","amount":10},{"token_id":"...","side":"SELL","type":"LIMIT","amount":5,"price":0.70}]'
```

### News

```bash
synthesis news list                             # Latest news
synthesis news event <event_id>                 # News for an event
```

### Other

```bash
synthesis whoami                                # Check current session
synthesis status                                # API health check
synthesis setup                                 # Guided first-time setup
synthesis upgrade                               # Update to latest version
synthesis shell                                 # Interactive REPL
synthesis --help                                # All commands
synthesis --version                             # Version info
```

## Interactive Shell

```bash
synthesis shell
```

```
synthesis> markets search "bitcoin"
synthesis> pm orderbook 48331043336612883...
synthesis> wallet balance
synthesis> -j markets list --limit 3
synthesis> exit
```

All commands work the same as the CLI, just without the `synthesis` prefix.

## For Scripts & Agents

The CLI is designed for programmatic use by scripts, AI agents, and LLMs:

```bash
# Always use -j for parseable output
synthesis -j markets list --limit 10

# Check success field
result=$(synthesis -j trade buy TOKEN_ID 100)
echo "$result" | jq '.success'

# Batch orders from a file
cat orders.json | xargs -0 synthesis -j trade batch

# Error handling
if ! synthesis -j wallet balance > /dev/null 2>&1; then
  echo "Not authenticated"
fi
```

**Key behaviors in JSON mode:**
- All output is valid JSON on stdout
- Errors use `{"success": false, "error": "..."}` format
- Exit code is non-zero on failure
- No spinners, colors, or interactive elements

## Requirements

- Node.js >= 18.0.0
- `@predictions/sdk` (installed automatically)

## License

MIT