# Ib Find Short Roll

> Find roll options for existing short positions OR find best covered call/put to open against long stock. Use when user asks about rolling shorts, finding roll candidates, writing covered calls, or managing option positions. Requires TWS or IB Gateway running locally.

- Skill: `staskh/ib-find-short-roll` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add staskh/ib-find-short-roll`
- Raw SKILL.md: https://api.skillmd.com/api/skills/staskh/ib-find-short-roll/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: staskh (https://skillmd.com/u/staskh)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/staskh/ib-find-short-roll

---


# IB Find Short Roll

Analyze roll options for short positions or find best short options to open against long stock using real-time data from Interactive Brokers.

## IB Connection

TWS or IB Gateway must be running locally with API enabled:
- **Paper trading** — port 7497
- **Live trading** — port 7496
- **`IB_PORT` env var** — default port when `--port` is omitted (e.g. `IB_PORT=4001` for a Gateway container). Precedence: `--port` flag > `IB_PORT` > built-in default. Set it in the shell or a `.env` file.

**Port fallback:** If the configured port fails, automatically retry on the other port.
If the retry succeeds, save to memory which account type worked (live/paper) and reuse it for all IB skill calls in this and future sessions — until the user explicitly asks for the other account.
If both ports fail, ask the user to verify that TWS or IB Gateway is running with API access enabled.

## Instructions

### Step 1: Gather Data

> **Note:** If `uv` is not installed or `pyproject.toml` is not found, replace `uv run python` with `python` in all commands below.

```bash
uv run python scripts/roll.py SYMBOL [--strike STRIKE] [--expiry YYYYMMDD] [--right C|P] [--port PORT] [--account ACCOUNT] [--iv-multiplier N]
```

The script returns JSON to stdout with all position and candidate data.

### Step 2: Format Report

Read `templates/markdown-template.md` for formatting instructions. Generate a markdown report from the JSON data and save to `sandbox/`.

### Step 3: Report Results

Present key findings to the user: recommended position, credit/debit, and the saved report path.

## Behavior

1. **If short option position exists** (`mode: "roll"`): Analyzes roll candidates to different expirations/strikes
2. **If long option position exists** (`mode: "spread"`): Finds best short call/put to create a vertical spread
3. **If long stock exists** (`mode: "new_short"`): Finds best covered call (or protective put) to open
4. **If none of the above**: Returns error (use --strike/--expiry to specify manually)

## Arguments

- `SYMBOL` - Ticker symbol (e.g., GOOG, AAPL, TSLA)
- `--strike` - Current short strike price (optional, auto-detects from portfolio)
- `--expiry` - Current short expiration in YYYYMMDD format (optional, auto-detects)
- `--right` - Option type: C for call, P for put (default: C)
- `--port` - IB port (default: 7497 for paper trading)
- `--account` - Specific account ID (optional)
- `--iv-multiplier` - Expected-move multiplier for strike band width (default: 2.0); increase for high-IV names to surface wider roll candidates

## JSON Output

The script outputs JSON with `mode` field indicating the analysis type:

### Common Fields
- `success` - Boolean
- `generated` - Timestamp
- `mode` - "roll", "spread", or "new_short"
- `symbol` - Ticker
- `underlying_price` - Current stock price
- `earnings_date` - Next earnings date or null
- `expirations_analyzed` - List of expiry dates checked

### Mode-specific Fields
- **roll**: `current_position` (includes `iv` and `delta` from IB greeks), `buy_to_close`, `roll_candidates` (dict of expiry -> candidates), `iv_multiplier`
- **spread**: `long_option`, `right`, `candidates_by_expiry`
- **new_short**: `long_position`, `right`, `candidates_by_expiry`, `iv_multiplier`

### Strike Band Logic (roll and new_short modes)
The strike search window is IV-aware: `half_band = iv_multiplier × ATM_IV × spot × √(T/365)` where T is the DTE of the nearest roll expiry. For roll mode, ATM IV comes from IB model greeks on the current position's quote; if unavailable, it is estimated from the option mid-price using the Brenner-Subrahmanyam approximation. For new_short mode, a conservative default IV of 30% is used. This makes the band automatically wider for high-IV underlyings without requiring a manual override.

## Example Usage

```bash
# Auto-detect GOOG position (short option, long option, or long stock)
uv run python scripts/roll.py GOOG --port 7497

# Specify exact short position to roll
uv run python scripts/roll.py GOOG --strike 350 --expiry 20260206 --right C

# Find short call to sell against long call (vertical spread)
uv run python scripts/roll.py AUR --right C

# Find covered put for long stock
uv run python scripts/roll.py TSLA --right P
```

## Dependencies

- `ib-async`
- `yfinance`


## Timezone

All timestamps and time-based calculations must use the `America/New_York` timezone. All JSON output must include `generated_at` (NY time string) and `data_delay` fields.