Every Yahoo Finance endpoint plus a SQLite portfolio, covered-call screener, and Chrome-cookie fallback the libraries don't ship.
yahoo-finance-pp-cli matches yfinance and yahoo-finance2 for raw endpoint coverage, then adds the things only a local store + agent-shaped CLI can do: cost-basis-aware portfolio performance, dividend income with yield-on-cost, a SQL-backed fundamentals screener, options moneyness + DTE filtering, and an auth login --chrome cookie escape hatch when Yahoo blocks your IP.
Created by @tmchow (Trevin Chow).
Authentication
Yahoo Finance has no API key — it requires a crumb+cookie handshake. The CLI auto-fetches the crumb on first call and persists cookies to ~/.config/yahoo-finance-pp-cli/. If your IP is rate-limited (cloud hosts and many international IPs are), run auth login --chrome to import a logged-in Chrome session so the crumb dance succeeds.
Quick Start
# Confirms the crumb handshake works from your IP.
yahoo-finance-pp-cli doctor
# Three live quotes, JSON-shaped, agent-narrow.
yahoo-finance-pp-cli quote list --symbols AAPL,MSFT,NVDA --json --select symbol,regularMarketPrice,regularMarketChangePercent
# Pulls daily chart for AAPL; auto-caches into the local SQLite store.
yahoo-finance-pp-cli chart AAPL --interval 1d --json
# Cross-endpoint daily briefing for a named watchlist — the killer transcendence command.
yahoo-finance-pp-cli digest --watchlist tech --agent
# Compose raw SQL against synced data — uniqueness of the local store.
yahoo-finance-pp-cli sql "SELECT symbol, MAX(close) FROM history GROUP BY symbol"
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
portfolio perf — Track YTD / 1Y / all-time returns on your holdings with cost basis, dividends, and current price baked in.
Reach for this when an agent needs to report 'how is my user's portfolio doing this year' — no single Yahoo Finance endpoint encodes cost basis.
yahoo-finance-pp-cli portfolio perf --agent
-
digest — One command: overnight news + biggest movers + earnings today + ex-div dates for everything on your watchlist.
Use as a single agent call for a 'daily market briefing' across a named set of tickers — replaces 4+ separate endpoint calls.
yahoo-finance-pp-cli digest --watchlist tech --agent
-
portfolio dividends — See total dividend income for the year, per-holding breakdown, and yield on cost.
Reach for this when the user asks 'how much have I earned in dividends this year' or 'what's my real yield on my JNJ position'.
yahoo-finance-pp-cli portfolio dividends --year 2026 --agent
-
insiders-net-buying — Surface companies where insiders are net buyers in the last N days, filtered to your watchlist.
Use when an agent needs a 'who's insiders actually buying' signal layer across the user's watchlist.
yahoo-finance-pp-cli insiders-net-buying --recent 30d --watchlist tech --agent
Agent-native compute
-
options-chain — Filter an options chain to ATM/OTM/ITM contracts within a days-to-expiration window.
Use when an agent needs to surface 'OTM weekly puts on AAPL near earnings' without parsing a thousand-row chain.
yahoo-finance-pp-cli options-chain AAPL --moneyness otm --max-dte 45 --agent
-
screen-local — Run arbitrary P/E, P/B, yield, margin, and growth filters against the data you've synced locally.
Use to compose custom value/growth screens an agent can apply to a synced universe, far beyond Yahoo's 12 canned screens.
yahoo-finance-pp-cli screen-local --pe-max 15 --roe-min 0.15 --agent
-
compare — Multi-symbol price-plus-dividend total return ranked over a range.
Use when comparing actual holding-period returns rather than price-only deltas — the only Yahoo CLI that does this offline.
yahoo-finance-pp-cli compare AAPL MSFT NVDA --range 1y --include-divs --agent
-
options-covered-calls — Scan your holdings for covered-call candidates by annualized yield and DTE.
Use to surface 'wheel-strategy' covered-call candidates from the user's actual stock positions.
yahoo-finance-pp-cli options-covered-calls --min-yield-annualized 0.10 --max-dte 45 --agent
-
watchlist correlate — Pairwise Pearson correlation across the symbols in a named watchlist over a date range.
Use when an agent needs to flag concentration risk inside a watchlist — 'is this 'tech' watchlist actually 80% AAPL exposure'.
yahoo-finance-pp-cli watchlist correlate tech --range 6m --agent
Reachability mitigation
-
auth login --chrome — Import your live Chrome session cookies when Yahoo's crumb handshake is blocked from your IP.
Reach for this when an agent's doctor reports 429 from the host's IP — Chrome's session cookies unblock the crumb handshake.
yahoo-finance-pp-cli auth login --chrome
Recipes
Daily market briefing across your watchlist
yahoo-finance-pp-cli digest --watchlist tech --agent
Single command returns overnight news, biggest movers, earnings today, and ex-div dates for the symbols in the named watchlist.
Year-to-date portfolio performance
yahoo-finance-pp-cli portfolio perf --agent --select symbol,unrealized_pl,total_return_pct
Joins cost basis with live quotes and reinvested dividends. The --select narrows the payload so an agent doesn't burn context on every row.
Find OTM puts on AAPL near 30 DTE
yahoo-finance-pp-cli options-chain AAPL --moneyness otm --max-dte 45 --type puts --agent
Filters the full chain client-side by moneyness and DTE; Yahoo's endpoint doesn't filter.
Custom SQL screen for cheap large caps
yahoo-finance-pp-cli screen-local --pe-max 15 --roe-min 0.15 --market-cap-min 10000000000 --agent
Runs against locally-synced fundamentals; Yahoo's remote screener has only 12 predefined IDs.
Raw SQL over the local store
yahoo-finance-pp-cli sql "SELECT symbol, ROUND(AVG(close), 2) AS avg_close FROM history WHERE date > date('now','-30 days') GROUP BY symbol ORDER BY avg_close DESC LIMIT 10"
Demonstrates the SQLite path; useful when an agent needs aggregations that no canned command covers.
Usage
Run yahoo-finance-pp-cli --help for the full command reference and flag list.
Commands
autocomplete
Legacy autocomplete (faster than search)
yahoo-finance-pp-cli autocomplete - Autocomplete symbols and company names
chart
Historical OHLCV price data
yahoo-finance-pp-cli chart <symbol> - Historical price chart data for a symbol
fundamentals
Time series of fundamentals (quarterly/annual)
yahoo-finance-pp-cli fundamentals <symbol> - Fundamentals time series (EPS, revenue, margin, cash flow, etc.)
insights
Company insights, valuation, and technical events
yahoo-finance-pp-cli insights - Insights for a symbol: technical events, valuation, research reports
lookup
Symbol search and lookup
yahoo-finance-pp-cli lookup - Search for symbols, news, and funds matching a query
options
Options chains for equities and ETFs
yahoo-finance-pp-cli options <symbol> - Options chain for a symbol (calls and puts)
quote
Real-time quotes and quote summaries
yahoo-finance-pp-cli quote list - Get current quotes for one or more symbolsyahoo-finance-pp-cli quote summary - Deep quote summary including price, fundamentals, ownership, and filings
recommendations
Symbols related by analyst recommendation
yahoo-finance-pp-cli recommendations <symbol> - Symbols that share recommendations with the given symbol
screener
Predefined and custom stock screeners
yahoo-finance-pp-cli screener - Run a predefined screener by ID
trending
Trending symbols by region
yahoo-finance-pp-cli trending <region> - Top trending symbols in a region right now
Output Formats
# Human-readable table (default in terminal, JSON when piped)
yahoo-finance-pp-cli autocomplete --query example-value
# JSON for scripting and agents
yahoo-finance-pp-cli autocomplete --query example-value --json
# Filter to specific fields
yahoo-finance-pp-cli autocomplete --query example-value --json --select id,name,status
# Dry run — show the request without sending
yahoo-finance-pp-cli autocomplete --query example-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
yahoo-finance-pp-cli autocomplete --query example-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
yahoo-finance-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/yahoo-finance-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- HTTP 429 from query1.finance.yahoo.com — Run
yahoo-finance-pp-cli auth login --chrome to import a logged-in Chrome session, then retry.
- Crumb appears in error responses but request still fails — Delete the cached session:
rm ~/.config/yahoo-finance-pp-cli/session.json and let the next call re-bootstrap.
- Quotes look stale — Free tier is delayed up to 15 minutes;
--extended-hours does not change that. Use a paid provider for sub-minute data.
portfolio perf shows zero positions — Seed your lots first: yahoo-finance-pp-cli portfolio add AAPL 100 --purchase-date 2025-01-15 --cost-basis 175.00.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press