optionctl

Opinionated CLI for finding unusual options activity in S&P 500 tickers.

What This Tool Does

optionctl scans all S&P 500 tickers by default.

It ranks contracts using an unusual-flow score weighted toward:

• Vol/OI (new opening activity signal)
• raw contract volume
• distance to the underlying (proximity)
• IV (small weight)

Defaults (Opinionated)

The default scan is tuned for unusual flow, not penny-option lottery tickets:

• max_price: 0.01
• min_volume: 250
• min_vol_oi: 1.0
• DTE: 0-15

Quick Start

uv run optionctl scan

This runs the default unusual-flow scan across the full S&P 500 universe.

Common Commands

# Tighten unusual threshold
uv run optionctl scan --min-vol-oi 2.0 --min-volume 500

# JSON / CSV output
uv run optionctl scan --output json
uv run optionctl scan --output csv

Scan Flags

Cache Commands

# Warm S&P 500 universe
uv run optionctl cache warm

# Warm all expirations
uv run optionctl cache warm --all

# Inspect / clear cache
uv run optionctl cache status
uv run optionctl cache clear

# Prune volume-history files
uv run optionctl cache prune-history --max-age 30

Development

make format
make check # static checks and package build
make test  # live SPY scan; requires Yahoo Finance access

make test uses the installed CLI and current market data. It updates the normal local cache and prediction history. It does not place trades. CI runs static checks and package checks without live services. Unit and mock suites are not part of this project.

optionctl version and optionctl --version print the package version. JSON scans write an array to stdout, including [] when no contract matches. Human tables also use stdout; progress and diagnostics use stderr.