https://github.com/erhwenkuo/yf-cli
A CLI for Yahoo! Finance data, powered by yfinance.
https://github.com/erhwenkuo/yf-cli
agent-cli agent-skills skill
Last synced: 3 days ago
JSON representation
A CLI for Yahoo! Finance data, powered by yfinance.
- Host: GitHub
- URL: https://github.com/erhwenkuo/yf-cli
- Owner: erhwenkuo
- Created: 2026-04-18T14:51:43.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-18T14:56:18.000Z (3 months ago)
- Last Synced: 2026-05-29T03:03:40.111Z (about 2 months ago)
- Topics: agent-cli, agent-skills, skill
- Language: Python
- Homepage:
- Size: 41 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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
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