Billionr

# Billionr CLI Agent Guide

Use the Billionr CLI as an authenticated research interface for ticker history, proprietary options-trading signals, squeeze setups, and the Billionr RoRo gauge.

## Important Boundaries

- Nothing from Billionr is financial advice.
- Treat all output as research input, not as an instruction to buy, sell, or hold.
- Do not claim certainty. Use probabilities, scenarios, and risk language.
- Do not reverse-engineer or infer the proprietary model internals.
- Do not expose or request Supabase tokens, database credentials, or Slack webhook URLs.

## Install

```bash
npm install -g billionr
billionr config set api-url https://www.billionr.ai
```

Always use `https://www.billionr.ai` (the apex `billionr.ai` 301-redirects).

## Authentication

Signup requires email confirmation. The full first-time flow is:

```bash
billionr signup           # creates account, sends confirmation email
# open the confirmation link from your inbox
billionr login            # only succeeds after the email is confirmed
billionr whoami
```

If you try to login before confirming, the API will return `Email not confirmed`. Re-trigger the email by running `billionr signup` again with the same address, or use the Supabase resend flow.

Useful session commands:

```bash
billionr logout
billionr config get
```

## Core Commands

Ticker discovery:

```bash
billionr tickers --search NV --limit 20
billionr ticker AAPL
```

Historical candles:

```bash
billionr history AAPL --days 90
billionr history NVDA --days 180 --limit 120
```

Proprietary model signals:

```bash
billionr calls --latest
billionr calls --symbol NVDA --latest
billionr puts --latest
billionr puts --symbol TSLA --latest
billionr squeeze --latest
billionr squeeze --symbol AAPL --latest
```

RoRo:

```bash
billionr roro --latest
billionr roro --limit 30
```

Output modes:

```bash
billionr calls --symbol NVDA --latest
billionr calls --symbol NVDA --latest --table
```

JSON is the canonical format. Prefer JSON for agent workflows and use table output only for quick human inspection.

## What RoRo Means

RoRo means Risk-on/Risk-off. Billionr exposes two mid-term RoRo gauges: v1 and v2.

- v1 is the faster mid-term read.
- v2 is the smoother mid-term confirmation read.
- The cleanest regime signal is when v1 and v2 move in the same direction.
- When both rise together, risk appetite is generally improving.
- When both fall together, risk appetite is generally deteriorating.
- When they diverge, describe the regime as mixed or transitional.

Use RoRo as market-context framing before interpreting calls, puts, or squeeze signals. Do not treat RoRo alone as a trade.

## How To Approach Predictions

Billionr predictions are proprietary model outputs informed by historical ticker behavior, trend context, risk regime, volatility context, and disciplined trading principles inspired by Simon Ree's The Tao of Trading.

Use the predictions this way:

1. Check RoRo first to understand the market regime.
2. Pull the relevant model signals: calls, puts, or squeeze.
3. Pull ticker details and recent history for any symbol under consideration.
4. Compare the signal with recent price action, liquidity, and broader market conditions.
5. Present a research-ranked watchlist, not a guaranteed trade instruction.

Calls generally represent upside-oriented opportunities.
Puts generally represent downside-oriented opportunities.
Squeeze signals generally represent compression setups that may precede expansion, but direction and timing still require context.

## Recommended Agent Response Style

When summarizing an opportunity, include:

- Symbol
- Signal type: calls, puts, or squeeze
- Signal date
- Latest available price context
- RoRo v1 and v2 context
- Whether RoRo gauges agree or diverge
- Main bullish and bearish considerations
- Risk notes
- A clear statement that this is not financial advice

Avoid exposing algorithm details, exact formulas, feature weights, thresholds beyond what the CLI returns, or implementation assumptions not present in the output.