Skip to content
adrpinoPublic

About

CLI to search stock market data

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

10 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

stonk πŸ“ˆ

A high-performance Rust CLI utility that aggregates financial valuation metrics, multi-year historical price trends, terminal ASCII/Unicode price charts, SEC EDGAR filings, earnings call transcripts, and corporate bond intelligenceβ€”formatted specifically for AI LLM prompt pipelines and human visual lookup.


Features

  • Multi-Quarter & Multi-Year Financial Statements (stonk financials): Standardized GAAP revenue, operating income, net income, margins, diluted EPS, YoY growth, and Free Cash Flow extracted from SEC EDGAR XBRL facts with capped Unicode sparklines (-q 12 quarters or -y 5 years).
  • Terminal Visual Price Charts (stonk chart): High-resolution Unicode/ASCII price line charts directly in the terminal with price axis levels, percentage changes, and high/low indicators.
  • Valuation & Fundamentals (stonk quote / stonk <TICKER>): Trailing/Forward P/E, PEG, EV/EBITDA, Price/Sales, Price/Book, operating margins, free cash flow, return on equity, and upcoming earnings dates.
  • Historical Price Trends (-H, --history): Token-optimized monthly candles (1y, 2y, 5y, 10y, max) with calculated performance metrics (52-week drawdown, 1-year and 5-year returns) consuming < 500 tokens for 5 years of data.
  • SEC EDGAR Filings (stonk sec): Real-time lookup of 10-K, 10-Q, 8-K, 4, S-1, S-3, 6-K, 20-F filings with direct document URLs. Automatically parses filing HTML into clean markdown financial tables and MD&A commentary (-p, --parse).
  • Earnings Call Transcripts (stonk transcript): Formatted quarterly earnings call transcripts with executive remarks and analyst Q&A sections (-q Q3 -y 2026).
  • Corporate Bond Intelligence (stonk bond): Scrapes live corporate debt offerings by stock ticker or ISIN/CUSIP (coupon rate, maturity date, current price, and Yield to Maturity).
  • AI-First Mode (--ai): Wraps data in clean markdown prompt containers optimized for direct piping into LLM CLIs (opencode, claude, gemini-cli).
  • Resilient Network Layer: Handles Yahoo session cookies and crumbs, browser Client Hints (Sec-CH-UA), SEC EDGAR User-Agent conventions, and broken pipe signals gracefully.

Installation

cargo install --path .

Commands & Usage

1. Multi-Quarter & Multi-Year Financial Statements (financials)

Fetch standardized GAAP financial statements (Executive Summary, Detailed Income Statement, Detailed Cash Flow, Balance Sheet & Solvency) directly from SEC EDGAR XBRL facts.

# Executive Summary (Revenue, Margins, EPS, Free Cash Flow)
stonk financials AAPL -q 12

# Detailed Income Statement (COGS, Gross Profit, R&D, SG&A, OpInc, NetInc, EPS)
stonk financials NVDA -q 8 --income

# Detailed Cash Flow Statement (OpCF, CapEx, FCF, FCF Margin, SBC, Dividends, Buybacks)
stonk financials MSFT -q 12 --cashflow

# Detailed Balance Sheet & Solvency (Cash, ST Inv, Total Debt, Net Cash, Current Ratio, Equity)
stonk financials GOOG -q 8 --balance

# 5 annual fiscal years prompt container for AI LLMs
stonk financials TSLA -y 5 --ai

# Single-line compact JSON dataset
stonk financials CRM -q 12 --compact

Terminal Table Previews

Executive Summary View (stonk financials AAPL -q 8):

=== Apple Inc. (AAPL) β€” Financials (Executive Summary, Quarterly, Last 8 Periods) ===

Period  End Date        Revenue  Gross Mgn  Op Margin Net Margin      EPS    YoY EPS         FCF   FCF Mgn
─────────────────────────────────────────────────────────────────────────────────────────────────────────
26-Q2   2026-06-27     $109.42B      50.1%      32.6%      27.2%    $2.02     +28.7%     $31.91B     29.2%
26-Q1   2026-03-28     $111.18B      49.3%      32.3%      26.6%    $2.01     +21.8%     $26.73B     24.0%
25-Q4   2025-12-27     $143.76B      48.2%      35.4%      29.3%    $2.84     +18.3%     $51.55B     35.9%
25-Q3   2025-09-27     $102.47B      47.2%      31.6%      26.8%    $1.84     +89.7%     $26.49B     25.8%
25-Q2   2025-06-28      $94.04B      46.5%      30.0%      24.9%    $1.57     +12.1%     $24.41B     26.0%
25-Q1   2025-03-29      $95.36B      47.1%      31.0%      26.0%    $1.65      +7.8%     $20.88B     21.9%
24-Q4   2024-12-28     $124.30B      46.9%      34.5%      29.2%    $2.40     +10.1%     $27.00B     21.7%
24-Q3   2024-09-28      $94.93B      46.2%      31.2%      15.5%    $0.97     -34.0%     $23.90B     25.2%

Revenue Trend:        β–‚β–…β–‚β–‚β–ƒβ–‡β–„β–„  [$94.04B - $143.76B]

Op Income Trend:      β–‚β–…β–‚β–‚β–ƒβ–‡β–„β–„  [$28.20B - $50.85B]

Net Income Trend:     β–‚β–†β–„β–„β–„β–‡β–…β–…  [$14.74B - $42.10B]

Free Cash Flow Trend: β–‚β–ƒβ–‚β–ƒβ–ƒβ–‡β–ƒβ–„  [$20.88B - $51.55B]

EPS Trend:            β–‚β–†β–„β–„β–„β–‡β–…β–…  [$0.97 - $2.84]

Detailed Income Statement View (stonk financials NVDA -q 8 --income):

=== NVIDIA CORP (NVDA) β€” Financials (Income Statement, Quarterly, Last 8 Periods) ===

Period  End Date      Revenue       COGS Gross Prof Gross Mgn        R&D       SG&A  Op Income   Op Mgn Net Income     EPS
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
26-Q3   2026-07-26    $96.22B    $24.08B    $72.14B     75.0%     $7.05B     $1.35B    $63.73B    66.2%    $59.69B   $2.46
26-Q2   2026-04-26    $81.61B    $20.46B    $61.16B     74.9%     $6.32B     $1.30B    $53.54B    65.6%    $58.32B   $2.39
26-Q1   2026-01-25    $68.13B    $17.03B    $51.09B     75.0%     $5.51B     $1.28B    $44.30B    65.0%    $42.96B   $1.76
25-Q4   2025-10-26    $57.01B    $15.16B    $41.85B     73.4%     $4.71B     $1.13B    $36.01B    63.2%    $31.91B   $1.30

Detailed Cash Flow Statement View (stonk financials MSFT -q 8 --cashflow):

=== MICROSOFT CORPORATION (MSFT) β€” Financials (Cash Flow Statement, Quarterly, Last 8 Periods) ===

Period  End Date          OpCF      CapEx         FCF   FCF Mgn        SBC  Dividends    Buybacks
─────────────────────────────────────────────────────────────────────────────────────────────────
26-Q2   2026-06-30     $55.44B    $35.80B     $19.64B     21.8%     $3.12B     $6.76B      $4.58B
26-Q1   2026-03-31     $46.68B    $30.88B     $15.80B     19.1%     $3.08B     $6.76B      $4.63B
25-Q4   2025-12-31     $35.76B    $29.88B      $5.88B      7.2%     $3.22B     $6.76B      $7.42B
25-Q3   2025-09-30     $45.06B    $19.39B     $25.66B     33.0%     $2.98B     $6.17B      $5.65B

Detailed Balance Sheet & Solvency View (stonk financials GOOG -q 8 --balance):

=== Alphabet Inc. (GOOG) β€” Financials (Balance Sheet & Solvency, Quarterly, Last 8 Periods) ===

Period  End Date     Cash+ST Inv   Short-Term  Total Assets   Total Debt      Net Cash  Curr Ratio  Shareholders Eq
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────
26-Q2   2026-06-30      $242.47B     $186.56B      $921.98B     $100.16B      $142.31B       2.72x         $640.48B
26-Q1   2026-03-31      $126.84B      $88.78B      $703.92B      $79.50B       $47.34B       1.92x         $478.75B
25-Q4   2025-12-31      $126.84B      $96.14B      $595.28B      $48.54B       $78.30B       2.01x         $415.26B
25-Q3   2025-09-30       $98.50B      $75.41B      $536.47B      $23.60B       $74.89B       1.75x         $386.87B

Total Cash Trend:     β–‚β–‚β–‚β–‚β–‚β–ƒβ–ƒβ–‡  [$93.23B - $242.47B]

Total Debt Trend:     β–‚β–‚β–‚β–ƒβ–ƒβ–„β–†β–‡  [$11.88B - $100.16B]

Net Cash Trend:       β–„β–„β–„β–ƒβ–ƒβ–„β–‚β–‡  [$47.34B - $142.31B]

Equity Trend:         β–‚β–‚β–‚β–ƒβ–ƒβ–„β–…β–‡  [$314.12B - $640.48B]

2. Terminal Visual Price Charts (chart)

# 1-month daily candle chart by default
stonk chart AAPL

# 5-day intraday chart with 15m intervals
stonk chart NVDA 5d -i 15m

# 1-year weekly trend
stonk chart TSM 1y

# 5-year macro price history
stonk chart META 5y

3. Stock Valuation & Price History (quote)

# Pretty-printed JSON dossier (shortcut)
stonk TSM

# Or using explicit subcommand
stonk quote TSM

# 5-year monthly candles formatted for AI prompt
stonk quote MU -H 5y --ai

# Compact single-line JSON
stonk quote NVDA --compact

4. SEC EDGAR Filings (sec)

# Retrieve latest 10-Q filing metadata and SEC archive link
stonk sec NVDA

# Specific form (e.g. 10-K, 8-K, Form 4, S-1)
stonk sec AAPL 10-K

# Parse filing HTML into clean markdown financial tables & MD&A sections
stonk sec AAPL 10-K -p --ai

5. Earnings Call Transcripts (transcript)

# Latest earnings call transcript (defaults to Q3 2026)
stonk transcript MSFT --ai

# Specific fiscal quarter and year
stonk transcript GOOGL -q Q2 -y 2026 --ai

6. Corporate Bonds & Debt Analysis (bond)

# List all active corporate bonds for a company
stonk bond META --ai

# Look up a specific bond by ISIN / CUSIP
stonk bond US037833DB33 --ai

7. Piping to AI CLI Agents

# Multi-quarter growth and margin analysis
stonk financials MCD -q 12 --ai | opencode "Analyze McDonald's quarterly margin progression and revenue growth trajectory"

# Comprehensive valuation & bull/bear thesis
stonk quote TSM -H 5y --ai | opencode "Analyze this 5-year valuation evolution and generate a bull vs bear thesis"

# Earnings call sentiment & forward guidance review
stonk transcript NVDA -q Q2 -y 2026 --ai | opencode "Summarize management guidance on data center revenue and margins"

# SEC 10-K statement review
stonk sec AAPL 10-K -p --ai | opencode "Extract all revenue breakdown items and segment margins"

# Debt & capital structure evaluation
stonk bond AAPL --ai | opencode "Evaluate Apple's corporate bond maturities and interest rate risk"

Subcommands & Options Reference

Global Flags

  • --ai: Output formatted as a markdown prompt container for LLMs.
  • --compact: Output single-line compact JSON.
  • -h, --help: Print comprehensive command help.

Command Reference

Subcommand Arguments & Flags Description
financials <TICKER> [-q <COUNT>] [-y <COUNT>] [--income|--cashflow|--balance|-s <TYPE>] Multi-quarter/multi-year GAAP financials (Executive, Income, Cash Flow, Balance Sheet) from SEC XBRL.
chart <TICKER> [RANGE] [-i <INTERVAL>] Render an ASCII/Unicode price chart in terminal (1d, 5d, 1mo, 3mo, 6mo, 1y, 5y, max).
quote <TICKER> [-H <RANGE>] Valuation fundamentals and historical monthly price candles (1y, 2y, 5y, 10y, max).
sec <TICKER> [FORM] [-p, --parse] SEC filing metadata and HTML table/MD&A parsing (10-K, 10-Q, 8-K, 4, S-1, S-3, 6-K, 20-F).
transcript <TICKER> [-q <QUARTER>] [-y <YEAR>] Quarterly earnings call transcripts (Q1, Q2, Q3, Q4, default year 2026).
bond <QUERY> Corporate bond yield and maturity lookup by ticker (META) or ISIN/CUSIP (US037833DB33).

Development & Testing

# Format code
cargo fmt --check

# Lint with clippy (zero warnings enforced)
cargo clippy --all-targets --all-features -- -D warnings

# Run offline unit test suite (runs in milliseconds)
cargo test

# Run live end-to-end network integration tests against SEC/Yahoo feeds
cargo test --test live_integration -- --ignored

About

CLI to search stock market data

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages