yf-finance

Query Yahoo Finance data from the command line using yf-cli.

Pre-flight Check

Always run this before any yf command.

command -v yf

If the command is not found, install it:

uv tool install yf-cli

Confirm the tool is ready before continuing:

yf --version

Never skip this check — assume nothing about the environment.

---

Command Catalogue

Real-time Quote

yf quote TICKER

Returns current price, daily change, volume, and market cap.

Historical OHLCV

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

yf info TICKER

Returns business summary, sector, industry, employee count, and key ratios.

Financials

yf financials TICKER [--type TYPE]

--type values: income (default), balance, cashflow. Returns the most recent annual statements.

Corporate Actions

yf dividends TICKER   # dividend history
yf splits TICKER      # stock split history
yf actions TICKER     # combined dividends and splits

Analyst Data

yf analyst TICKER

Returns price targets (low / mean / high), buy/hold/sell recommendation counts, and EPS estimates.

Ownership

yf holders TICKER

Returns major holders, institutional holders, and insider transactions.

Earnings Calendar

yf calendar TICKER

Returns next earnings date, EPS estimate, and revenue estimate.

Options Chain

yf options TICKER [--output FORMAT]

Returns calls and puts for the nearest expiry. Use --output json to process programmatically.

Search

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

yf screen --preset PRESET

Common presets: most_actives, day_gainers, day_losers, undervalued_large_caps, growth_technology_stocks, aggressive_small_caps.

Market Overview

yf market

Returns sector performance and broad market indices.

News

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
• Output format details and examples: references/output-formats.md
• Worked input/output examples: assets/examples.md