npm package: @marketmotion/cli
Description: Market Motion CLI — Intelligence terminal for prediction markets. Search 25K+ entities, scan cross-venue arbitrage, monitor real-time alerts, and explore the entity graph from your terminal.
Author: Market Motion
Latest version: 0.5.0

# @marketmotion/cli

Intelligence terminal for prediction markets. Search 25,000+ entities, scan cross-venue arbitrage, monitor real-time alerts, and explore the entity graph — all from your terminal.

[![npm version](https://img.shields.io/npm/v/@marketmotion/cli)](https://www.npmjs.com/package/@marketmotion/cli)

## Install

```bash
npm install -g @marketmotion/cli
```

## Update

```bash
motion update
```

The CLI checks for updates automatically once per day and notifies you when a new version is available. You can also update manually with `npm install -g @marketmotion/cli`.

## Quick Start

1. Get your API key at [marketmotion.xyz/developer](https://marketmotion.xyz/developer)
2. Authenticate:
   ```bash
   motion auth login <your-api-key>
   ```
3. Start exploring:
   ```bash
   motion entities search "LeBron James"
   motion markets trending
   motion arb scan
   ```

## Commands

| Command | Description |
|---------|-------------|
| `motion auth login <key>` | Authenticate with your API key |
| `motion auth logout` | Remove stored credentials |
| `motion auth status` | Show current auth status and usage |
| `motion auth signup` | Open the developer portal to get an API key |
| `motion entities search <query>` | Search 25K+ entities (people, teams, orgs, assets) |
| `motion entity get <slug>` | Get detailed entity profile with markets and relationships |
| `motion entity search <query>` | Search entities (same as `entities search`) |
| `motion entity graph <slug>` | Explore entity relationship graph |
| `motion markets trending` | Top trending and high-volume markets across Hyperliquid |
| `motion markets search <query>` | Search prediction markets on Polymarket, Kalshi |
| `motion markets filter` | Filter markets by category and sort |
| `motion alerts list` | List recent alerts (injury, arb, political, etc.) |
| `motion alerts watch` | Live alert feed with polling |
| `motion arb scan` | Scan for cross-venue mispricings (Polymarket vs Kalshi) |
| `motion arb scan --all` | Show all admin-approved cross-venue matches |
| `motion news trending` | Top market-relevant news |
| `motion news entity <slug>` | News for a specific entity by slug |
| `motion graph <slug>` | Explore entity relationship graph (alias) |
| `motion webhook list` | List configured webhooks |
| `motion webhook create <url>` | Create a webhook endpoint |
| `motion webhook delete <id>` | Delete a webhook |
| `motion update` | Update the CLI to the latest version |
| `motion dashboard` | Interactive TUI dashboard |

All commands support `--json` for raw JSON output and `--help` for usage details.

## Authentication

Market Motion CLI requires an API key for all data commands. Keys are created through the developer portal.

1. Visit [marketmotion.xyz/developer](https://marketmotion.xyz/developer)
2. Create a free account and generate an API key
3. Run `motion auth login <key>` or set `MOTION_API_KEY` as an environment variable

```bash
# Store key in config
motion auth login mt_live_abc123

# Or use environment variable
export MOTION_API_KEY=mt_live_abc123

# Or pipe it in
echo "mt_live_abc123" | motion auth login
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `MOTION_API_KEY` | API key (overrides stored config) | — |
| `MOTION_API_URL` | Base API URL | `https://api.marketmotion.xyz` |

Config is stored at `~/.config/motion/config.json` (managed by the `conf` package).

## Examples

### Entity Intelligence

```bash
# Search entities across categories
motion entities search "Trump" --category politics
motion entities search "Bitcoin" --type asset
motion entities search "Lakers" --category sports

# Get full entity profile (use the slug from search results)
motion entity get us-president-trump
motion entity get crypto-l1-btc
motion entity get nba-lal --json
```

### Market Discovery

```bash
# Browse trending markets (Hyperliquid perps, sorted by price change)
motion markets trending

# Search prediction markets across venues
motion markets search "Bitcoin" --venue polymarket
motion markets search "president" --venue kalshi

# Filter and sort by category
motion markets filter --category crypto --sort volume --limit 10
motion markets filter --category politics --sort volume
```

### Arbitrage Scanning

```bash
# Find mispricings across Polymarket + Kalshi
motion arb scan
motion arb scan --min-spread 3 --actionable

# Browse all cross-venue matched markets
motion arb scan --all
motion arb scan --all --category politics

# JSON output for programmatic use
motion arb scan --all --json
```

### Real-Time Alerts

```bash
# Latest injury alerts
motion alerts list --type injury

# All recent alerts
motion alerts list --limit 50

# Live feed (polls every 15 seconds)
motion alerts watch --type injury --interval 15
```

### Entity Graph

```bash
# Explore entity relationships
motion graph us-president-trump --depth 2
motion entity graph crypto-l1-btc

# JSON output for piping
motion graph crypto-l1-btc --json | jq '.graph.nodes | length'
```

### Webhooks

```bash
# Set up real-time event delivery
motion webhook create https://api.example.com/hooks --events alert.injury,alert.arbitrage
motion webhook list
motion webhook deliveries <webhook-id>
```

## Links

- [API Documentation](https://docs.marketmotion.xyz)
- [Web App](https://marketmotion.xyz)
- [Developer Portal](https://marketmotion.xyz/developer)