yf CLI

A command-line interface for Yahoo! Finance data, powered by yfinance and Click.

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 (recommended package manager)

Installation

git clone <repo-url>
cd yf_cli

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

Verify:

yf --version
yf --help

Shell Completion

# 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

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

yf history — Historical OHLCV prices

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

yf info AAPL
yf info TSLA --output json

yf financials — Financial statements

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

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

yf analyst — Analyst data

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

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

yf calendar AAPL
yf calendar MSFT --output json

yf options — Options chains

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

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

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

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

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

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

# 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

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