yfin-cli 0.2.0__tar.gz → 0.2.2__tar.gz

yfin_cli-0.2.2/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Check tag matches package version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $version"
+            exit 1
+          fi
+
+      - name: Run tests
+        run: uv run --frozen pytest -q
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --trusted-publishing always

{yfin_cli-0.2.0 → yfin_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: yfin-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: A command-line interface for Yahoo Finance data
 License-Expression: MIT
 License-File: LICENSE
@@ -8,7 +8,7 @@ Requires-Python: >=3.10
 Requires-Dist: lxml>=6.0.2
 Requires-Dist: rich>=14.2.0
 Requires-Dist: typer>=0.21.1
-Requires-Dist: yfinance>=1.1.0
+Requires-Dist: yfinance>=1.8.0
 Description-Content-Type: text/markdown
 
 # yfin-cli

{yfin_cli-0.2.0 → yfin_cli-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "yfin-cli"
-version = "0.2.0"
+version = "0.2.2"
 license = "MIT"
 description = "A command-line interface for Yahoo Finance data"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -8,7 +8,7 @@ requires-python = ">=3.10"
 dependencies = [
     "lxml>=6.0.2",
     "typer>=0.21.1",
-    "yfinance>=1.1.0",
+    "yfinance>=1.8.0",
     "rich>=14.2.0",
 ]
 

yfin_cli-0.2.2/skills/yahoo-finance/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: yahoo-finance
+description: Provides comprehensive financial market data and news from Yahoo Finance. Use this when the user needs to screen for stocks using granular filters, or requires historical price data, news articles, financial statements, and sector analysis.
+---
+
+# Yahoo Finance
+
+`yfin` is the ultimate command-line interface for financial data, it provides immediate access to a massive spectrum of market intelligence—from historical price data and real-time news to deep-dive corporate financials, earnings calendars, and institutional holding records. While it excels at standard lookups across sectors and industries, the tool's true power lies in its robust stock screener: a highly flexible query engine capable of handling complex boolean logic and granular filtering, empowering you to search for and isolate exactly the assets you need based on virtually any criteria.
+
+## Prerequisites
+
+Assume `yfin` is already installed. However, if you attempt to run a `yfin` command and receive a "command not found" error, you MUST install it using one of the following methods:
+
+```bash
+uv tool install yfin-cli
+# or
+pipx install yfin-cli
+# or
+pip install yfin-cli
+```
+
+## Quick Examples
+
+```bash
+# Get historical stock data
+yfin history AAPL
+
+# Get quick summary metrics
+yfin fast-info TSLA
+
+# Get news for a stock
+yfin news MSFT
+
+# Check market status
+yfin market-status
+
+# View quarterly income statement
+yfin income-stmt MSFT --frequency quarterly
+
+# Screen stocks by simple filters
+yfin screen --filter "sector eq Technology" --filter "intradaymarketcap gt 100000000000"
+
+# Use a predefined screener
+yfin screen --predefined day_gainers
+
+# Screen stocks by complex filters
+yfin screen --json-query '{ "operator": "and", "queries": ["region eq us", "intradaymarketcap gte 2000000000", "dayvolume gt 5000000"] }' --sort-field dayvolume --sort-order desc --limit 5
+
+```
+
+## Available Commands
+
+For the complete command reference with all options and parameters, see the corresponding reference.
+
+| Category       | Commands                                                                                                                                                                                                                                                                                                        | Reference                  |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| **Stock**      | `history`, `dividends`, `fast-info`, `info`, `news`, `market-status`                                                                                                                                                                                                                                            | `references/stock.md`      |
+| **Calendar**   | `calendar-earnings`, `calendar-economic-events`, `calendar-ipo`                                                                                                                                                                                                                                                 | `references/calendar.md`   |
+| **Financials** | `income-stmt`, `balance-sheet`, `cashflow`, `earnings-dates`, `sec-filings`                                                                                                                                                                                                                                     | `references/financials.md` |
+| **Analysis**   | `recommendations`, `upgrades-downgrades`, `price-targets`, `earnings-estimate`, `revenue-estimate`, `earnings-history`, `eps-trend`, `eps-revisions`, `growth-estimates`, `insider-purchases`, `insider-transactions`, `insider-roster-holders`, `major-holders`, `institutional-holders`, `mutualfund-holders` | `references/analysis.md`   |
+| **Screen**     | `screen`, `screen-query-fields`, `screen-query-values`, `screen-predefined-queries`                                                                                                                                                                                                                             | `references/screen.md`     |
+| **Sector**     | `sector-keys`, `sector-industries`, `sector-overview`, `sector-research-reports`, `sector-top-companies`, `sector-top-etfs`, `sector-top-mutual-funds`                                                                                                                                                          | `references/sector.md`     |
+| **Industry**   | `industry-overview`, `industry-research-reports`, `industry-top-companies`, `industry-top-growth-companies`, `industry-top-performing-companies`                                                                                                                                                                | `references/industry.md`   |

yfin_cli-0.2.2/skills/yahoo-finance/references/analysis.md

@@ -0,0 +1,240 @@
+# Analysis
+
+## `recommendations`
+
+Get analyst recommendations — number of buy, sell, and hold ratings across time periods.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin recommendations AAPL
+yfin recommendations TSLA
+```
+
+---
+
+## `upgrades-downgrades`
+
+Get the history of analyst upgrades and downgrades.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin upgrades-downgrades AAPL
+```
+
+---
+
+## `price-targets`
+
+Get analyst price targets (current, low, high, mean, median).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin price-targets TSLA
+```
+
+---
+
+## `earnings-estimate`
+
+Get analyst earnings estimates for upcoming periods.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin earnings-estimate AAPL
+```
+
+---
+
+## `revenue-estimate`
+
+Get analyst revenue estimates for upcoming periods.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin revenue-estimate MSFT
+```
+
+---
+
+## `earnings-history`
+
+Get historical earnings — actual vs. estimated EPS.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin earnings-history GOOG
+```
+
+---
+
+## `eps-trend`
+
+Get the EPS trend — how estimates have changed over time.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin eps-trend AAPL
+```
+
+---
+
+## `eps-revisions`
+
+Get EPS revisions — analyst estimate changes (up/down revisions).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin eps-revisions NVDA
+```
+
+---
+
+## `growth-estimates`
+
+Get analyst growth estimates for a stock.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin growth-estimates AMZN
+```
+
+---
+
+## `insider-purchases`
+
+Get insider purchase activity summary.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin insider-purchases AAPL
+```
+
+---
+
+## `insider-transactions`
+
+Get detailed insider transaction records (buys, sells, exercises).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin insider-transactions TSLA
+```
+
+---
+
+## `insider-roster-holders`
+
+Get the insider roster — list of insiders and their holdings.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin insider-roster-holders MSFT
+```
+
+---
+
+## `major-holders`
+
+Get major holders breakdown (% held by insiders, institutions, etc.).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin major-holders AAPL
+```
+
+---
+
+## `institutional-holders`
+
+Get the top institutional holders and their positions.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin institutional-holders GOOG
+```
+
+---
+
+## `mutualfund-holders`
+
+Get the top mutual fund holders and their positions.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+yfin mutualfund-holders MSFT
+```

yfin_cli-0.2.2/skills/yahoo-finance/references/calendar.md

@@ -0,0 +1,75 @@
+# Calendar
+
+## `calendar-earnings`
+
+Get the earnings calendar — upcoming and recent earnings announcements.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `--start` | option | — | today | Start date (`YYYY-MM-DD`) |
+| `--end` | option | — | today + 7 days | End date (`YYYY-MM-DD`) |
+| `--limit` | option | — | `12` | Maximum number of results |
+| `--offset` | option | — | `0` | Offset for pagination |
+| `--market-cap` | option | — | `0` | Minimum market cap filter |
+
+**Examples:**
+
+```bash
+# Get this week's earnings
+yfin calendar-earnings
+
+# Get earnings for a specific date range
+yfin calendar-earnings --start 2026-02-10 --end 2026-02-14
+
+# Get top 5 earnings by market cap
+yfin calendar-earnings --limit 5
+
+# Paginate results
+yfin calendar-earnings --limit 10 --offset 10
+```
+
+---
+
+## `calendar-ipo`
+
+Get the IPO calendar — upcoming initial public offerings.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `--start` | option | — | today | Start date (`YYYY-MM-DD`) |
+| `--end` | option | — | today + 7 days | End date (`YYYY-MM-DD`) |
+| `--limit` | option | — | `12` | Maximum number of results |
+| `--offset` | option | — | `0` | Offset for pagination |
+
+**Examples:**
+
+```bash
+# Get upcoming IPOs this week
+yfin calendar-ipo
+
+# Get IPOs for next month
+yfin calendar-ipo --start 2026-03-01 --end 2026-03-31
+```
+
+---
+
+## `calendar-economic-events`
+
+Get the economic events calendar — scheduled economic data releases and events.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `--start` | option | — | today | Start date (`YYYY-MM-DD`) |
+| `--end` | option | — | today + 7 days | End date (`YYYY-MM-DD`) |
+| `--limit` | option | — | `12` | Maximum number of results |
+| `--offset` | option | — | `0` | Offset for pagination |
+
+**Examples:**
+
+```bash
+# Get this week's economic events
+yfin calendar-economic-events
+
+# Get events for a specific week with more results
+yfin calendar-economic-events --start 2026-02-10 --end 2026-02-14 --limit 50
+```

yfin_cli-0.2.2/skills/yahoo-finance/references/financials.md

@@ -0,0 +1,107 @@
+# Financials
+
+## `income-stmt`
+
+Get the income statement for a ticker.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+| `--frequency` | option | — | `yearly` | Frequency: `yearly`, `quarterly`, `trailing` |
+
+**Examples:**
+
+```bash
+# Get annual income statement
+yfin income-stmt AAPL
+
+# Get quarterly income statement
+yfin income-stmt MSFT --frequency quarterly
+
+# Get trailing twelve months
+yfin income-stmt GOOG --frequency trailing
+```
+
+---
+
+## `balance-sheet`
+
+Get the balance sheet for a ticker.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+| `--frequency` | option | — | `yearly` | Frequency: `yearly`, `quarterly` |
+
+**Examples:**
+
+```bash
+# Get annual balance sheet
+yfin balance-sheet AAPL
+
+# Get quarterly balance sheet
+yfin balance-sheet TSLA --frequency quarterly
+```
+
+---
+
+## `cashflow`
+
+Get the cash flow statement for a ticker.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+| `--frequency` | option | — | `yearly` | Frequency: `yearly`, `quarterly`, `trailing` |
+
+**Examples:**
+
+```bash
+# Get annual cash flow
+yfin cashflow AAPL
+
+# Get quarterly cash flow
+yfin cashflow NVDA --frequency quarterly
+```
+
+---
+
+## `earnings-dates`
+
+Get earnings dates, estimates, and reported EPS for a ticker.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+| `--limit` | option | — | `12` | Maximum number of results |
+| `--offset` | option | — | `0` | Offset for pagination |
+
+**Examples:**
+
+```bash
+# Get upcoming/recent earnings dates
+yfin earnings-dates AAPL
+
+# Get more earnings dates
+yfin earnings-dates MSFT --limit 20
+
+# Paginate to older earnings
+yfin earnings-dates GOOG --limit 10 --offset 10
+```
+
+---
+
+## `sec-filings`
+
+Get SEC filings for a ticker.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `TICKER` | argument | ✅ | — | Stock ticker symbol |
+
+**Examples:**
+
+```bash
+# Get SEC filings for Apple
+yfin sec-filings AAPL
+```

yfin_cli-0.2.2/skills/yahoo-finance/references/industry.md

@@ -0,0 +1,81 @@
+# Industry
+
+## `industry-overview`
+
+Get overview information for an industry.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `KEY` | argument | ✅ | — | A valid industry key (use `yfin sector-industries <sector-key>` to find) |
+
+**Examples:**
+
+```bash
+yfin industry-overview semiconductors
+yfin industry-overview software-application
+```
+
+---
+
+## `industry-research-reports`
+
+Get research reports related to an industry.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `KEY` | argument | ✅ | — | A valid industry key |
+
+**Examples:**
+
+```bash
+yfin industry-research-reports biotechnology
+```
+
+---
+
+## `industry-top-companies`
+
+Get the top companies within an industry.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `KEY` | argument | ✅ | — | A valid industry key |
+
+**Examples:**
+
+```bash
+yfin industry-top-companies semiconductors
+yfin industry-top-companies internet-retail
+```
+
+---
+
+## `industry-top-growth-companies`
+
+Get the top growth companies in an industry.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `KEY` | argument | ✅ | — | A valid industry key |
+
+**Examples:**
+
+```bash
+yfin industry-top-growth-companies software-infrastructure
+```
+
+---
+
+## `industry-top-performing-companies`
+
+Get the top performing companies in an industry.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `KEY` | argument | ✅ | — | A valid industry key |
+
+**Examples:**
+
+```bash
+yfin industry-top-performing-companies auto-manufacturers
+```