npm package: @dawnai/cli
Description: User-facing Dawn CLI
Latest version: 1.3.0

# @dawnai/cli

The Dawn CLI — build and run autonomous prediction market trading strategies from your terminal.

## Requirements

- Node.js 20+
- Python 3.12+ (managed automatically via the bundled SDK)
- [OpenWallet (ows)](https://openwallet.sh/) for live trading

## Install

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

Verify:

```bash
dawn --version
```

## Quick Start

### Option 1 — Run a template strategy (recommended)

No wallet needed. Runs with simulated funds in paper mode.

```bash
# 1. Authenticate
dawn auth login

# 2. Browse available templates
dawn template list

# 3. Launch a template in paper mode
dawn template launch <name> --name "my-run"

# 4. Monitor
dawn strategy logs <run_id> --tail 50

# 5. Stop
dawn strategy stop <run_id>
```

### Option 2 — Build a strategy from scratch

```bash
# 1. Authenticate
dawn auth login

# 2. Explore SDK tools and docs
dawn tool docs polymarket
dawn tool run polymarket_event_search --input '{"query": "NBA finals", "limit": 5}'

# 3. Write a strategy and launch it
dawn strategy launch strategy.py --name "my-strategy"        # paper mode
dawn strategy launch strategy.py --name "my-strategy" --live # live mode

# 4. Monitor
dawn strategy logs <run_id> --tail 50

# 5. Stop
dawn strategy stop <run_id>
```

---

## Commands

### Auth

```bash
dawn auth login       # authenticate via browser (Google OAuth)
dawn auth status      # check current auth state
dawn auth logout      # clear stored credentials
dawn auth url [<url>] # view or set the API base URL
```

### Wallet

Wallets are managed by [OpenWallet (ows)](https://openwallet.sh/). Dawn stores your active wallet selection locally.

```bash
dawn wallet list                    # list all ows wallets
dawn wallet use <address-or-name>   # select active wallet
dawn wallet current                 # show active wallet + Polygon balances
```

### Templates

Pre-built strategies ready to run. Downloaded to `~/.dawn-cli/templates/<name>.py` — fully editable after download.

```bash
dawn template list                                   # browse available templates
dawn template launch <name> --name <run-name>         # download and run in paper mode
dawn template launch <name> --name <run-name> --live  # run live (requires funded wallet)
```

**Modifying a template:**

```bash
dawn template launch <name> --name <run-name>   # 1. download + launch
dawn strategy stop <run_id>                     # 2. stop
# edit ~/.dawn-cli/templates/<name>.py          # 3. change BUDGET_USD, logic, etc.
dawn strategy launch ~/.dawn-cli/templates/<name>.py --name <run-name>  # 4. relaunch
```

### Strategy

Strategies are plain Python files with a time loop. They run as local background processes.

```bash
dawn strategy launch <strategy.py> --name <name> [--live]
dawn strategy list
dawn strategy logs <run_id> [--tail N]
dawn strategy stop <run_id>
dawn strategy positions <run_id>
```

- Without `--live`, strategies run in **paper mode** — trades are simulated, no real funds used.
- `--live` requires a wallet selected via `dawn wallet use`.
- Each run gets a unique `run_id`. Multiple strategies can run simultaneously.
- **Budget is set in the strategy code** via `BUDGET_USD` — the strategy enforces it, there is no CLI flag.

### Wallet Trading & Positions

Buy, sell, and view live on-chain positions directly from the active wallet.

```bash
dawn wallet buy <token_id> <amount>              # buy tokens (prompts for confirmation)
dawn wallet sell <token_id> [--amount <n>]        # sell tokens (auto-redeems if market resolved)
dawn wallet redeem-all                            # redeem all resolved positions
dawn wallet positions open [--page <n>]           # open positions (expanded view)
dawn wallet positions closed [--page <n>]         # closed positions
dawn wallet positions redeemable [--page <n>]     # redeemable positions only
dawn wallet trades [--page <n>]                   # trade history
```

### Tools

Browse and call Dawn SDK tools directly without writing a strategy.

```bash
dawn tool list                           # list all available tools
dawn tool run <tool_name> --input <json> # call a tool with JSON input
dawn tool docs                           # list available doc modules
dawn tool docs <module>                  # print full reference for a module
```

Available doc modules: `overview`, `directive`, `polymarket`, `portfolio`, `crypto`, `social`, `sports`, `web`, `utils`

### Skills

Install Dawn skills for AI assistants (Claude Code, Gemini CLI, Codex CLI).

```bash
dawn skill list
dawn skill install [--force] [--dir <path>]
```

### Update

```bash
dawn update   # install the latest version from npm + refresh SDK and skills
```

---

## Writing Strategies

Strategies are plain Python files. The recommended pattern is a simple time loop:

```python
import time
from decimal import Decimal
from dawnai import load_config, save_config
from dawnai.strategy.tools import polymarket_buy_token, read_portfolio

def run_once(config: dict):
    budget_usd = Decimal(str(config["budget_usd"]))
    # Budget guard — always check before buying
    total_invested = Decimal(str(config.get("total_invested", "0")))
    remaining = budget_usd - total_invested
    if remaining < Decimal("1"):
        print(f"Budget exhausted (${total_invested}/${budget_usd}). Holding.")
        return

    # your strategy logic here

def main():
    config = load_config()
    duration_hours = config.get("duration_hours", 1)
    interval_minutes = config.get("interval_minutes", 5)
    iterations = int((duration_hours * 60) / interval_minutes)
    print(f"Strategy starting | Budget: ${config['budget_usd']} (hard limit)")
    for i in range(iterations):
        config = load_config()
        print(f"[{i+1}/{iterations}] Running...")
        try:
            run_once(config)
        except Exception as e:
            print(f"Error: {e}")
        if i < iterations - 1:
            time.sleep(interval_minutes * 60)

if __name__ == "__main__":
    main()
```

Run `dawn tool docs directive` for the full strategy coding guidelines, and `dawn tool docs polymarket` for the complete Polymarket tool reference.

---

## Live Trading

Live trading uses [OpenWallet (ows)](https://openwallet.sh/) for local key management — your private keys never leave your machine.

1. Install ows and create a wallet:
   ```bash
   ows wallet create --name main
   ```
2. Fund the wallet on Polygon:
   - **USDC.e** — the stablecoin used for trades. ⚠️ This is **not** the same as regular USDC. When funding, select the Polygon network and specifically USDC.e. Sending regular USDC will not work for trading.
   - **POL** — small amount needed for gas fees (~$1–2 is enough)
3. Select the wallet in Dawn:
   ```bash
   dawn wallet use main
   dawn wallet current   # confirm balances
   ```
4. Launch with `--live`:
   ```bash
   dawn strategy launch strategy.py --name "my-strategy" --live
   ```

When a trade executes, the API returns an unsigned EIP-1559 transaction. The CLI signs it locally via `ows sign tx` and broadcasts it directly to Polygon via RPC — no private keys are sent to the Dawn backend.

---

## Environment Variables

| Variable | Description |
|---|---|
| `DAWNAI_API_KEY` | Auth token. Set automatically on `dawn auth login`. Can be set manually for headless/CI use. |
| `DAWN_LOCAL_WALLET_NAME` | ows wallet name for live trading. Set automatically from `dawn wallet use`. |
| `DAWN_LOCAL_WALLET_ADDRESS` | EOA address for the active wallet. Set automatically from `dawn wallet use`. |
| `DAWN_CLI_HOME` | Override config directory (default: `~/.dawn-cli`). |

## File Locations

| Path | Description |
|---|---|
| `~/.dawn-cli/config.json` | Auth token and active wallet selection |
| `~/.dawn-cli/runs.json` | Strategy run metadata (run_id, pid, mode, logs path) |
| `~/.dawn-cli/logs/<run_id>.log` | Per-run strategy output logs |
| `~/.dawn-cli/templates/<name>.py` | Downloaded template strategies |
| `~/.dawn-cli/.venv/` | Python virtual environment with the Dawn SDK |
| `~/.ows/bin/ows` | OpenWallet CLI binary |