Metadata-Version: 2.4
Name: yf-cli
Version: 0.2.0
Summary: A CLI for Yahoo! Finance data powered by yfinance and Click
Project-URL: Repository, https://github.com/erhwenkuo/yf-cli
Project-URL: Issues, https://github.com/erhwenkuo/yf-cli/issues
Author-email: Erhwen Kuo <erhwenkuo@gmail.com>
License: MIT
Keywords: cli,finance,stocks,yahoo-finance,yfinance
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: click>=8.1
Requires-Dist: pandas>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: yfinance>=0.2.50
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# yf CLI

A command-line interface for Yahoo! Finance data, powered by [yfinance](https://github.com/ranaroussi/yfinance) and [Click](https://click.palletsprojects.com/).

## Overview

`yf` gives you instant access to stock quotes, historical prices, financial statements,
analyst ratings, options chains, market screeners, and more — all from your terminal.

## Requirements

- Python 3.13+
- [uv](https://github.com/astral-sh/uv) (recommended package manager)

## Installation

```bash
git clone <repo-url>
cd yf_cli

uv venv
source .venv/bin/activate
uv pip install -e .
```

Verify:

```bash
yf --version
yf --help
```

## Shell Completion

```bash
# bash — add to ~/.bashrc
eval "$(_YF_COMPLETE=bash_source yf)"

# zsh — add to ~/.zshrc
eval "$(_YF_COMPLETE=zsh_source yf)"

# fish — add to ~/.config/fish/completions/yf.fish
_YF_COMPLETE=fish_source yf | source
```

Or run `yf completion` to print instructions for all shells.

## Commands

### `yf quote` — Real-time quotes

```bash
yf quote AAPL
yf quote AAPL MSFT GOOGL TSLA NVDA
yf quote AAPL --output json
```

### `yf history` — Historical OHLCV prices

```bash
yf history AAPL                                          # 1 month, daily (default)
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

# Periods:   1d 5d 1mo 3mo 6mo 1y 2y 5y 10y ytd max
# Intervals: 1m 2m 5m 15m 30m 60m 90m 1h 1d 5d 1wk 1mo 3mo
```

### `yf info` — Company overview

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

### `yf financials` — Financial statements

```bash
yf financials AAPL                                       # annual income statement
yf financials AAPL --type balance --freq quarterly
yf financials AAPL --type cashflow --freq ttm --output json

# --type:  income (default) | balance | cashflow
# --freq:  annual (default) | quarterly | ttm
```

### `yf dividends` / `yf splits` / `yf actions`

```bash
yf dividends KO
yf splits AAPL
yf actions AAPL --output csv
```

### `yf analyst` — Analyst data

```bash
yf analyst AAPL                                          # price targets (default)
yf analyst AAPL --type recommendations
yf analyst AAPL --type upgrades
yf analyst AAPL --type estimates --output json

# --type: targets (default) | recommendations | upgrades | estimates
```

### `yf holders` — Ownership data

```bash
yf holders AAPL                                          # major holders (default)
yf holders MSFT --type institutional
yf holders TSLA --type insider --output csv

# --type: major (default) | institutional | mutualfund | insider
```

### `yf calendar` — Earnings calendar

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

### `yf options` — Options chains

```bash
yf options AAPL                                          # list expiry dates
yf options AAPL --expiry 2026-06-18                      # calls + puts (default)
yf options AAPL --expiry 2026-06-18 --type calls
yf options AAPL --expiry 2026-06-18 --output csv

# --type: both (default) | calls | puts
# ITM rows are highlighted in green
```

### `yf search` — Search tickers and news

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

# --type: both (default) | quotes | news
```

### `yf screen` — Market screener

```bash
yf screen --list                                         # show available presets
yf screen --preset day-gainers
yf screen --preset most-active --limit 10
yf screen --preset undervalued-growth --output json
```

Available presets: `day-gainers` `day-losers` `most-active` `most-shorted`
`aggressive-small-caps` `small-cap-gainers` `growth-tech` `undervalued-growth`
`undervalued-large-caps` `conservative-foreign-funds` `high-yield-bond`
`portfolio-anchors` `solid-large-growth-funds` `solid-midcap-growth-funds`
`top-mutual-funds` `top-etfs-us` `top-performing-etfs` `technology-etfs` `bond-etfs`

### `yf market` — Market overview & sectors

```bash
yf market                                                # US market status
yf market --list                                         # available sectors
yf market --sector technology
yf market --sector energy --top etfs
yf market --sector healthcare --output json

# --top: companies (default) | etfs | mutual-funds
```

Available sectors: `basic-materials` `communication-services` `consumer-cyclical`
`consumer-defensive` `energy` `financial-services` `healthcare` `industrials`
`real-estate` `technology` `utilities`

### `yf news` — Latest news

```bash
yf news AAPL
yf news NVDA --limit 5
yf news TSLA --verbose                                   # full summaries + URLs
yf news MSFT --output json
```

### `yf completion` — Shell completion setup

```bash
yf completion          # instructions for all shells
yf completion bash
yf completion zsh
yf completion fish
```

## Global Options

```
--no-color    Disable Rich colour output
--version     Show version and exit
--help        Show help for any command
```

## Practical Examples

```bash
# Morning market check
yf quote AAPL MSFT GOOGL AMZN NVDA
yf screen --preset day-gainers --limit 10

# Deep-dive a stock
yf info NVDA
yf financials NVDA --type income --freq quarterly
yf analyst NVDA --type recommendations
yf holders NVDA --type institutional

# Options flow
yf options SPY
yf options SPY --expiry 2026-06-18 --type calls

# Export for spreadsheet / analysis
yf history AAPL --period 5y --output csv > aapl_5y.csv
yf financials AAPL --type balance --output json > aapl_balance.json
yf holders MSFT --type institutional --output csv > msft_holders.csv
```

## Development

```bash
source .venv/bin/activate

make install       # install with dev dependencies
make lint          # ruff check
make test          # pytest
make test-cov      # pytest with coverage report

# End-to-end smoke test (hits live Yahoo Finance API)
bash scripts/smoke_test.sh
```

## License

MIT
