Skill: erhwenkuo/yf-finance (version 1.0.0)

--- name: yf-finance description: > Fetch real-time and historical financial data from Yahoo Finance using yf-cli. Use when the user asks about stock prices, company financials, earnings calendars, analyst recommendations, options chains, dividends, market screeners, or financial news. Supports any publicly-traded ticker symbol. license: MIT compatibility: Requires Python 3.13+, uv, and yf-cli installed via `uv tool install yf-cli`. Internet access required. metadata: author: erhwenkuo version: "1.0" allowed-tools: Bash(yf:*) Bash(uv:*) Bash(command:*) --- # yf-finance Query Yahoo Finance data from the command line using `yf-cli`. ## Pre-flight Check **Always run this before any `yf` command.** ```bash command -v yf ``` If the command is not found, install it: ```bash uv tool install yf-cli ``` Confirm the tool is ready before continuing: ```bash yf --version ``` Never skip this check — assume nothing about the environment. --- ## Command Catalogue ### Real-time Quote ```bash yf quote TICKER ``` Returns current price, daily change, volume, and market cap. ### Historical OHLCV ```bash yf history TICKER [--period PERIOD] [--interval INTERVAL] [--output FORMAT] ``` | Flag | Default | Common values | |------|---------|---------------| | `--period` | `1mo` | `1d` `5d` `1mo` `3mo` `6mo` `1y` `2y` `5y` `10y` `ytd` `max` | | `--interval` | `1d` | `1m` `5m` `15m` `30m` `60m` `1d` `1wk` `1mo` | | `--output` | table | `json` `csv` | ### Company Info ```bash yf info TICKER ``` Returns business summary, sector, industry, employee count, and key ratios. ### Financials ```bash yf financials TICKER [--type TYPE] ``` `--type` values: `income` (default), `balance`, `cashflow`. Returns the most recent annual statements. ### Corporate Actions ```bash yf dividends TICKER # dividend history yf splits TICKER # stock split history yf actions TICKER # combined dividends and splits ``` ### Analyst Data ```bash yf analyst TICKER ``` Returns price targets (low / mean / high), buy/hold/sell recommendation counts, and EPS estimates. ### Ownership ```bash yf holders TICKER ``` Returns major holders, institutional holders, and insider transactions. ### Earnings Calendar ```bash yf calendar TICKER ``` Returns next earnings date, EPS estimate, and revenue estimate. ### Options Chain ```bash yf options TICKER [--output FORMAT] ``` Returns calls and puts for the nearest expiry. Use `--output json` to process programmatically. ### Search ```bash yf search QUERY ``` Resolves a company name or partial ticker to a symbol. Use this when the user does not know the exact ticker. ### Market Screener ```bash yf screen --preset PRESET ``` Common presets: `most_actives`, `day_gainers`, `day_losers`, `undervalued_large_caps`, `growth_technology_stocks`, `aggressive_small_caps`. ### Market Overview ```bash yf market ``` Returns sector performance and broad market indices. ### News ```bash yf news TICKER ``` Returns the latest headlines and article links for a ticker. --- ## Output Format Guidance | Format | Flag | Use when | |--------|------|----------| | Table (default) | _(none)_ | Displaying results directly to the user | | JSON | `--output json` | Parsing values, computing statistics, chaining commands | | CSV | `--output csv` | Exporting data for spreadsheet use | Add `--no-color` in environments that do not support ANSI escape codes. --- ## Decision Guide | User intent | Command | |-------------|---------| | "What is the current price of X?" | `yf quote TICKER` | | "Show me X's stock history / chart data" | `yf history TICKER` | | "Tell me about company X" | `yf info TICKER` | | "Show X's income statement / balance sheet" | `yf financials TICKER --type income\|balance\|cashflow` | | "When does X report earnings?" | `yf calendar TICKER` | | "What do analysts think of X?" | `yf analyst TICKER` | | "Who owns X?" | `yf holders TICKER` | | "Show X's options" | `yf options TICKER` | | "What are today's top movers?" | `yf screen --preset most_actives\|day_gainers\|day_losers` | | "How is the market doing?" | `yf market` | | "Latest news on X" | `yf news TICKER` | | Unknown ticker or company name | `yf search "company name"` | --- ## Edge Cases - **Unknown ticker** — if `yf quote` returns no data, run `yf search QUERY` first to resolve the correct symbol. - **Delisted or OTC tickers** — some symbols are unavailable on Yahoo Finance; inform the user and suggest an alternative ticker if known. - **Rate limiting** — if Yahoo Finance returns an error or empty response, wait a few seconds and retry once before reporting failure. - **Empty options chain** — not all tickers have listed options; handle gracefully and inform the user. - **Market closed** — `yf quote` still returns the last closing price; note this to the user when markets are closed. --- ## Reference Files - Detailed flag tables for every subcommand: [references/commands.md](references/commands.md) - Output format details and examples: [references/output-formats.md](references/output-formats.md) - Worked input/output examples: [assets/examples.md](assets/examples.md)

path: assets/examples.md
content: # Worked Examples

Real input/output examples for the most common use cases.
All outputs were captured from `yf-cli 0.2.0`.

---

## 1. Get Current Price and Daily Change for AAPL

**Command**
```bash
yf quote AAPL
```

**Output**
```
┏━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃        ┃        ┃        ┃        ┃        ┃       ┃        ┃        ┃   Mkt ┃
┃ Symbol ┃  Price ┃ Change ┃  Chg % ┃   Open ┃  High ┃    Low ┃ Volume ┃   Cap ┃
┡━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ AAPL   │ 269.41 │  -2.09 │ -0.77% │ 271.44 │ 272.8 │ 269.31 │      — │ 3959… │
└────────┴────────┴────────┴────────┴────────┴───────┴────────┴────────┴───────┘
```

**Multiple tickers at once**
```bash
yf quote AAPL MSFT GOOGL
```

---

## 2. Pull 1-Year Weekly OHLCV for TSLA as JSON

**Command**
```bash
yf history TSLA --period 1y --interval 1wk --output json
```

**JSON structure** — keyed by OHLCV field, each containing a date → value map:
```json
{
  "Open":   { "2025-04-21": 230.26, "2025-04-28": 288.98, "..." : "..." },
  "High":   { "2025-04-21": 286.85, "2025-04-28": 294.86, "..." : "..." },
  "Low":    { "2025-04-21": 222.79, "2025-04-28": 270.78, "..." : "..." },
  "Close":  { "2025-04-21": 284.95, "2025-04-28": 287.21, "..." : "..." },
  "Volume": { "2025-04-21": 631033300, "2025-04-28": 603713200, "..." : "..." },
  "Dividends":    { "...": 0.0 },
  "Stock Splits": { "...": 0.0 }
}
```

**Compute the 52-week price range from JSON output**
```bash
yf history TSLA --period 1y --interval 1wk --output json | python3 -c "
import json, sys
data = json.load(sys.stdin)
highs = list(data['High'].values())
lows  = list(data['Low'].values())
print(f'52-week High: {max(highs):.2f}')
print(f'52-week Low:  {min(lows):.2f}')
"
```

---

## 3. Compare Annual Revenue and Net Income for MSFT

**Command**
```bash
yf financials MSFT --output json
```

**Extract and compare the two most recent fiscal years**
```bash
yf financials MSFT --output json | python3 -c "
import json, sys
data = json.load(sys.stdin)
for period in list(data.keys())[:2]:
    rev = data[period].get('TotalRevenue', 0)
    ni  = data[period].get('NetIncome', 0)
    margin = round(ni / rev * 100, 1) if rev else None
    print(f'{period}: Revenue \${rev/1e9:.1f}B  Net Income \${ni/1e9:.1f}B  Margin {margin}%')
"
```

**Output**
```
2025-06-30: Revenue $281.7B  Net Income $101.8B  Margin 36.1%
2024-06-30: Revenue $245.1B  Net Income $88.1B   Margin 36.0%
```

**Other statement types**
```bash
yf financials MSFT --type balance --freq quarterly
yf financials MSFT --type cashflow --freq ttm --output json
```

---

## 4. Retrieve Next Earnings Date for NVDA

**Command**
```bash
yf calendar NVDA
```

**Output**
```
╭──────────── NVDA — Earnings Calendar ────────────╮
│   Dividend Date                 2026-04-01       │
│   Ex-Dividend Date              2026-03-11       │
│   Earnings Date                 2026-05-21       │
│   Earnings High                 1.99             │
│   Earnings Low                  1.69             │
│   Earnings Average              1.7753           │
│   Revenue High                  85,512,000,000   │
│   Revenue Low                   77,896,000,000   │
│   Revenue Average               78,799,090,450   │
╰──────────────────────────────────────────────────╯
```

**As JSON for programmatic use**
```bash
yf calendar NVDA --output json
```

---

## 5. Screen for Large-Cap Value Stocks

**Command**
```bash
yf screen --preset undervalued-large-caps --limit 5
```

**Output**
```
Screener — undervalued-large-caps  (5 results)
┏━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┓
┃ # ┃ Symbol ┃ Name                       ┃  Price ┃  Change ┃  Chg % ┃    Volume ┃ Mkt Cap ┃
┡━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━┩
│ 1 │ WF     │ Woori Financial Group Inc. │ 72.765 │ -0.4950 │ -0.68% │    46,993 │  17.73B │
│ 2 │ WES    │ Western Midstream Partners │  40.32 │ -0.3700 │ -0.91% │   277,935 │  16.45B │
│ 3 │ WBS    │ Webster Financial Corp     │  72.94 │ -0.1100 │ -0.15% │   747,342 │  11.76B │
│ 4 │ VIRT   │ Virtu Financial, Inc.      │  49.67 │ -0.8900 │ -1.76% │    90,578 │  10.67B │
│ 5 │ VG     │ Venture Global, Inc.       │ 11.625 │ +0.1750 │ +1.53% │ 3,567,776 │  28.86B │
└───┴────────┴────────────────────────────┴────────┴─────────┴────────┴───────────┴─────────┘
```

**List all available presets**
```bash
yf screen --list
```

---

## 6. Look Up an Unknown Ticker with `yf search`

Use this when the user knows a company name but not its ticker symbol.

**Command**
```bash
yf search "nvidia" --type quotes --limit 3
```

**Output**
```
                        Quotes — "nvidia"
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓
┃ Symbol  ┃ Name                            ┃ Type   ┃ Exchange  ┃ Score ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩
│ NVDA    │ NVIDIA Corporation              │ EQUITY │ NASDAQ    │ 29944 │
│ NVD.DE  │ NVIDIA Corporation              │ EQUITY │ XETRA     │ 20011 │
│ 3NVD.AS │ Leverage Shares 3x NVIDIA ETP S │ EQUITY │ Amsterdam │ 20004 │
└─────────┴─────────────────────────────────┴────────┴───────────┴───────┘
```

Pick the result with the highest `Score` on the target exchange (NASDAQ/NYSE for US stocks).
Then use the resolved symbol in subsequent commands:

```bash
yf quote NVDA
yf analyst NVDA --type recommendations
```


path: references/output-formats.md
content: # Output Formats

All `yf` commands support an `--output` / `-o` flag that controls how results are rendered.
Available values depend on the command — check [commands.md](commands.md) for per-command support.

---

## Comparison

| Format | Flag | Supported by | Best for |
|--------|------|--------------|----------|
| Table (default) | _(none)_ | all commands | Displaying results directly to the user |
| JSON | `--output json` | all commands | Parsing values, computing statistics, chaining commands |
| CSV | `--output csv` | most commands* | Exporting data for spreadsheet or downstream processing |

\* `calendar`, `info`, `market`, `news`, `search` do not support CSV.

---

## Table (default)

Rich-formatted table with borders and aligned columns. Uses ANSI colour codes to highlight
positive/negative changes.

```
yf quote AAPL
```

```
┏━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃        ┃        ┃        ┃        ┃        ┃       ┃        ┃        ┃   Mkt ┃
┃ Symbol ┃  Price ┃ Change ┃  Chg % ┃   Open ┃  High ┃    Low ┃ Volume ┃   Cap ┃
┡━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ AAPL   │ 269.37 │  -2.13 │ -0.78% │ 271.44 │ 272.8 │ 269.31 │      — │ 3959… │
└────────┴────────┴────────┴────────┴────────┴───────┴────────┴────────┴───────┘
```

**Use when:** the result is the final answer to show the user.

---

## JSON

Structured output. Returns either an array (for list results like `quote`, `options`) or an
object (for keyed results like `financials`).

```
yf quote AAPL --output json
```

```json
[
  {
    "symbol": "AAPL",
    "currency": "USD",
    "last_price": 269.45,
    "previous_close": 271.5,
    "open": 271.44,
    "day_high": 272.8,
    "day_low": 269.31,
    "volume": null,
    "market_cap": 3960356340118.0,
    "fifty_day_average": 260.51,
    "two_hundred_day_average": 252.44,
    "change": -2.05,
    "change_pct": -0.76
  }
]
```

**Use when:**
- You need to extract a specific field (e.g. `last_price`, `change_pct`)
- You are passing data to a second command or computation
- You want to compare values across multiple tickers

**Tip:** pipe into `python3 -c` or `jq` for quick field extraction:
```bash
yf quote AAPL MSFT --output json | python3 -c "
import json, sys
for r in json.load(sys.stdin):
    print(r['symbol'], r['last_price'])
"
```

---

## CSV

Comma-separated values with a header row. No ANSI codes, no borders.

```
yf quote AAPL --output csv
```

```
symbol,currency,last_price,previous_close,open,day_high,day_low,volume,market_cap,fifty_day_average,two_hundred_day_average,change,change_pct
AAPL,USD,269.45,271.5,271.44,272.8,269.31,,3960356340118.0,260.51,252.44,-2.05,-0.76
```

**Use when:**
- The user wants to save data to a file (`> data.csv`)
- The user wants to open results in a spreadsheet

**Redirect to file:**
```bash
yf history AAPL --period 1y --output csv > aapl_1y.csv
```

---

## Disabling Colour (`--no-color`)

`--no-color` is a **global flag** — it must appear before the subcommand name:

```bash
yf --no-color quote AAPL        # correct
yf quote AAPL --no-color        # error: No such option
```

**Use when:**
- Output will be logged or piped to a file
- The terminal does not support ANSI escape codes
- The agent's environment strips colour codes unpredictably


path: references/commands.md
content: # yf-cli Command Reference

Full flag reference for every `yf` subcommand. Load this file when you need precise flag names,
allowed values, or defaults beyond what `SKILL.md` covers.

---

## `yf quote`

```
yf quote [OPTIONS] TICKERS...
```

Accepts one or more space-separated tickers.

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--output` | `-o` | `table` `json` `csv` | `table` |

**Examples**
```bash
yf quote AAPL
yf quote AAPL MSFT GOOGL
yf quote TSLA --output json
```

---

## `yf history`

```
yf history [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--period` | `-p` | `1d` `5d` `1mo` `3mo` `6mo` `1y` `2y` `5y` `10y` `ytd` `max` | `1mo` |
| `--interval` | `-i` | `1m` `2m` `5m` `15m` `30m` `60m` `90m` `1h` `1d` `5d` `1wk` `1mo` `3mo` | `1d` |
| `--start` | | `YYYY-MM-DD` | — |
| `--end` | | `YYYY-MM-DD` | — |
| `--output` | `-o` | `table` `json` `csv` | `table` |

`--period` is ignored when `--start` / `--end` are given.

**Examples**
```bash
yf history AAPL
yf history AAPL --period 6mo --interval 1wk
yf history AAPL --start 2024-01-01 --end 2024-12-31
yf history AAPL --period 1y --output csv > aapl.csv
```

---

## `yf info`

```
yf info [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--output` | `-o` | `table` `json` | `table` |

**Examples**
```bash
yf info AAPL
yf info TSLA --output json
```

---

## `yf financials`

```
yf financials [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--type` | | `income` `balance` `cashflow` | `income` |
| `--freq` | | `annual` `quarterly` `ttm` | `annual` |
| `--output` | `-o` | `table` `json` `csv` | `table` |

`ttm` (trailing twelve months) is not available for the balance sheet.

**Examples**
```bash
yf financials AAPL
yf financials AAPL --type balance --freq quarterly
yf financials AAPL --type cashflow --freq ttm --output json
```

---

## `yf dividends`

```
yf dividends [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--output` | `-o` | `table` `json` `csv` | `table` |

**Examples**
```bash
yf dividends AAPL
yf dividends KO --output csv
```

---

## `yf splits`

```
yf splits [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--output` | `-o` | `table` `json` `csv` | `table` |

**Examples**
```bash
yf splits AAPL
yf splits TSLA --output json
```

---

## `yf actions`

```
yf actions [OPTIONS] TICKER
```

Combined view of dividends and splits in a single table.

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--output` | `-o` | `table` `json` `csv` | `table` |

**Examples**
```bash
yf actions AAPL
yf actions MSFT --output csv
```

---

## `yf analyst`

```
yf analyst [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--type` | | `targets` `recommendations` `upgrades` `estimates` | `targets` |
| `--output` | `-o` | `table` `json` `csv` | `table` |

| Type | Description |
|------|-------------|
| `targets` | Analyst price targets (low / mean / high) |
| `recommendations` | Ratings summary (Strong Buy / Buy / Hold / Sell) |
| `upgrades` | Recent upgrades and downgrades |
| `estimates` | EPS estimates |

**Examples**
```bash
yf analyst AAPL
yf analyst AAPL --type recommendations
yf analyst AAPL --type upgrades --output json
```

---

## `yf holders`

```
yf holders [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--type` | | `major` `institutional` `mutualfund` `insider` | `major` |
| `--output` | `-o` | `table` `json` `csv` | `table` |

**Examples**
```bash
yf holders AAPL
yf holders MSFT --type institutional
yf holders TSLA --type insider --output csv
```

---

## `yf calendar`

```
yf calendar [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--output` | `-o` | `table` `json` | `table` |

**Examples**
```bash
yf calendar AAPL
yf calendar MSFT --output json
```

---

## `yf options`

```
yf options [OPTIONS] TICKER
```

Omit `--expiry` to list available expiration dates first.

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--expiry` | `-e` | `YYYY-MM-DD` | — (lists dates) |
| `--type` | | `both` `calls` `puts` | `both` |
| `--output` | `-o` | `table` `json` `csv` | `table` |

**Examples**
```bash
yf options AAPL                                  # list expiry dates
yf options AAPL --expiry 2025-06-20
yf options AAPL --expiry 2025-06-20 --type calls
yf options AAPL --expiry 2025-06-20 --output csv
```

---

## `yf search`

```
yf search [OPTIONS] QUERY
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--type` | | `both` `quotes` `news` | `both` |
| `--limit` | `-n` | integer | `10` |
| `--output` | `-o` | `table` `json` | `table` |

**Examples**
```bash
yf search "electric vehicles"
yf search AAPL --type news --limit 5
yf search "semiconductor" --type quotes --output json
```

---

## `yf screen`

```
yf screen [OPTIONS]
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--preset` | `-p` | see table below | — |
| `--limit` | `-n` | integer | `25` |
| `--list` | | flag | — |
| `--output` | `-o` | `table` `json` | `table` |

Use `--list` to print all available presets.

| Preset | Description |
|--------|-------------|
| `day-gainers` | Stocks with the highest % gain today |
| `day-losers` | Stocks with the biggest % drop today |
| `most-active` | Highest trading volume today |
| `most-shorted` | Most heavily shorted stocks |
| `aggressive-small-caps` | Small-cap stocks with aggressive growth |
| `small-cap-gainers` | Gaining small-cap stocks |
| `growth-tech` | Growth-oriented technology stocks |
| `undervalued-growth` | Undervalued stocks with growth potential |
| `undervalued-large-caps` | Large-cap stocks trading below value |
| `conservative-foreign-funds` | Conservative international mutual funds |
| `high-yield-bond` | High-yield bond funds |
| `portfolio-anchors` | Stable, foundational holdings |
| `solid-large-growth-funds` | Large-cap growth mutual funds |
| `solid-midcap-growth-funds` | Mid-cap growth mutual funds |
| `top-mutual-funds` | Top-performing mutual funds |
| `top-etfs-us` | Top US ETFs |
| `top-performing-etfs` | Best-performing ETFs |
| `technology-etfs` | Technology sector ETFs |
| `bond-etfs` | Bond ETFs |

**Examples**
```bash
yf screen --list
yf screen --preset day-gainers
yf screen --preset most-active --limit 10 --output json
```

---

## `yf market`

```
yf market [OPTIONS]
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--sector` | `-s` | `basic-materials` `communication-services` `consumer-cyclical` `consumer-defensive` `energy` `financial-services` `healthcare` `industrials` `real-estate` `technology` `utilities` | — |
| `--top` | `-t` | `companies` `etfs` `mutual-funds` | `companies` |
| `--list` | | flag | — |
| `--output` | `-o` | `table` `json` | `table` |

**Examples**
```bash
yf market
yf market --list
yf market --sector technology
yf market --sector energy --top etfs
yf market --sector healthcare --output json
```

---

## `yf news`

```
yf news [OPTIONS] TICKER
```

| Flag | Short | Values | Default |
|------|-------|--------|---------|
| `--limit` | `-n` | integer | `10` |
| `--verbose` | `-v` | flag | off |
| `--output` | `-o` | `table` `json` | `table` |

`--verbose` adds full article summaries to the output.

**Examples**
```bash
yf news AAPL
yf news NVDA --limit 5
yf news TSLA --verbose
yf news MSFT --output json
```

---

## Global Flag

| Flag | Applies to | Description |
|------|-----------|-------------|
| `--no-color` | all commands | Disable ANSI colour codes in output |

```bash
yf quote AAPL --no-color
```

---

## JSON Response Schemas

### `yf quote --output json`

Returns an array, one object per ticker.

```json
[
  {
    "symbol": "AAPL",
    "currency": "USD",
    "last_price": 269.39,
    "previous_close": 271.5,
    "open": 271.44,
    "day_high": 272.8,
    "day_low": 269.35,
    "volume": null,
    "market_cap": 3959400939044.0,
    "fifty_day_average": 260.51,
    "two_hundred_day_average": 252.44,
    "change": -2.115,
    "change_pct": -0.78
  }
]
```

### `yf financials --output json`

Returns an object keyed by fiscal period date. Each key maps to a flat object of line-item names → values (floats or null).

```json
{
  "2025-09-30": {
    "TotalRevenue": 416161000000.0,
    "GrossProfit": 195201000000.0,
    "OperatingIncome": 133050000000.0,
    "EBITDA": 144748000000.0,
    "NetIncome": 112010000000.0,
    "DilutedEPS": 7.46,
    "BasicEPS": 7.49
  }
}
```

### `yf options --expiry DATE --output json`

Returns an object with `"calls"` and/or `"puts"` arrays (depending on `--type`). Each element represents one contract.

```json
{
  "calls": [
    {
      "contractSymbol": "AAPL260422C00190000",
      "lastTradeDate": "2026-04-21 13:39:26+00:00",
      "strike": 190.0,
      "lastPrice": 81.17,
      "bid": 79.95,
      "ask": 83.2,
      "change": -1.25,
      "percentChange": -1.52,
      "volume": 4.0,
      "openInterest": 1,
      "impliedVolatility": 3.44,
      "inTheMoney": true,
      "contractSize": "REGULAR",
      "currency": "USD"
    }
  ]
}
```

When `--expiry` is omitted, the output is a plain table of available expiration dates (not JSON).


path: scripts/install.sh
content: #!/usr/bin/env bash
# Verify yf-cli is installed; install via uv if missing.
set -euo pipefail

if ! command -v yf &>/dev/null; then
  echo "yf-cli not found — installing via uv..."
  uv tool install yf-cli
else
  echo "yf-cli $(yf --version) is ready."
fi


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)