screenercli 0.1.0

CLI tool that scrapes screener.in and returns structured financial data optimised for LLM agents.

screener-cli

A Python command-line tool that scrapes screener.in company pages and returns structured financial data optimised for consumption by LLM coding agents (JSON by default) or human-readable terminal output.

---

Features

• Fetches all major financial sections: Quarterly Results, Profit & Loss, Balance Sheet, Cash Flow, Key Ratios, Shareholding Pattern, and Pros/Cons.
• Outputs clean, normalised JSON (commas stripped, % values as floats, empty cells as null).
• Optional --format text mode renders colour-coded tables in the terminal using Rich.
• TTL-based in-memory cache (5 minutes) so multiple sub-commands on the same ticker only fetch the page once per session.
• Automatic fallback from consolidated → standalone with a warning when the consolidated view is unavailable.
• Graceful error handling for missing sections, rate-limiting (HTTP 429 with exponential back-off), and invalid tickers.

---

Requirements

• Python 3.11+
• An internet connection (screener.in is a public site; no API key required)

---

Installation

From PyPI (recommended)

pip install screenercli

From source (for development)

git clone <repo-url> screener-cli
cd screener-cli
pip install -e .

After installation the screener command is available in your shell.

---

Usage

screener [OPTIONS] SYMBOL COMMAND [ARGS]...

Global options

Option	Values	Default	Description
--view	consolidated / standalone	consolidated	Which balance sheet view to fetch
--format	json / text	json	Output format
--no-cache	flag	off	Bypass the in-memory TTL cache
--version	—	—	Print version and exit

Commands

Command	Description
quarterly-results	Last 13 quarters of P&L
profit-loss	Annual P&L with compounded growth tables
balance-sheet	Annual Balance Sheet
cash-flow	Annual Cash Flow statement
ratios	Key operating ratios over the years
shareholding	Quarterly promoter / FII / DII / public holding
pros-cons	Screener-generated pros, cons, about blurb and key metrics
peer-comparison	Industry peers with valuation and performance metrics
all	All sections combined into one JSON payload

---

Examples

Get quarterly results (JSON — ready for an agent)

screener RELIANCE quarterly-results

{
  "section": "Quarterly Results",
  "unit": "Rs. Crores",
  "currency": "INR",
  "period_type": "quarterly",
  "headers": ["Jun 2023", "Sep 2023", "Dec 2023", "Mar 2024", "Jun 2024"],
  "rows": [
    {"label": "Sales", "values": [207559, 231886, 225086, 236533, 231784], ...},
    {"label": "Net Profit", "values": [18258, 19878, 19641, 21243, 17445], ...}
  ],
  "footnotes": []
}

Get balance sheet as human-readable table

screener --format text RELIANCE balance-sheet

Get standalone profit & loss for TCS

screener --view standalone TCS profit-loss

Get all data sections as a single JSON payload

screener INFY all

Pipe output to a file for offline agent consumption

screener HDFC all > hdfc_data.json

Get pros/cons and company about

screener --format text WIPRO pros-cons

Get peer comparison (JSON)

screener RELIANCE peer-comparison

Get peer comparison as a terminal table

screener --format text TCS peer-comparison

---

JSON Output Schema

Every financial-table command returns an object matching the following structure:

{
  "section": "string",
  "unit": "Rs. Crores",
  "currency": "INR",
  "period_type": "annual | quarterly",
  "headers": ["Mar 2020", "Mar 2021", ...],
  "rows": [
    {
      "label": "Sales",
      "values": [123456, 234567, null],
      "unit": null,
      "is_subtotal": false
    }
  ],
  "footnotes": []
}

The all command wraps everything under a top-level envelope:

{
  "symbol": "RELIANCE",
  "view": "consolidated",
  "scraped_at": "2026-03-13T10:00:00+00:00",
  "source_url": "https://www.screener.in/company/RELIANCE/consolidated/",
  "sections": {
    "quarterly_results": { ... },
    "profit_loss": {
      "table": { ... },
      "growth_tables": [
        {"label": "Compounded Sales Growth", "periods": ["10 Years", "5 Years"], "values": ["14%", "12%"]}
      ]
    },
    "balance_sheet": { ... },
    "cash_flow": { ... },
    "ratios": { ... },
    "shareholding": {
      "period_type": "quarterly",
      "headers": [...],
      "rows": [...],
      "latest": {"Promoters": 49.6, "FIIs": 24.3, "DIIs": 13.5, "Public": 12.6}
    },
    "pros_cons": {
      "pros": ["..."],
      "cons": ["..."],
      "about": "Reliance Industries Limited...",
      "key_metrics": {"Market Cap": "17,45,678 Cr", "P/E": "24.5"}
    },
    "peer_comparison": {
      "sector": "Energy",
      "industry": "Oil, Gas & Consumable Fuels",
      "sub_industry": "Petroleum Products",
      "sub_sub_industry": "Refineries & Marketing",
      "indices": ["BSE Sensex", "Nifty 50", "BSE 500"],
      "columns": ["Name", "CMP Rs.", "P/E", "Mar Cap Rs.Cr.", "Div Yld %", "NP Qtr Rs.Cr.", "Qtr Profit Var %", "Sales Qtr Rs.Cr.", "Qtr Sales Var %", "ROCE %"],
      "peers": [
        {"rank": 1, "name": "Reliance Industries", "url": "/company/RELIANCE/", "values": {"CMP Rs.": 1380.7, "P/E": 24.35, "Mar Cap Rs.Cr.": 1868897.82, "Div Yld %": 0.4, "ROCE %": 9.69}},
        {"rank": 2, "name": "I O C L",            "url": "/company/IOC/",      "values": {"CMP Rs.": 156.54, "P/E": 6.18, "Mar Cap Rs.Cr.": 221067.66, "Div Yld %": 4.47, "ROCE %": 7.36}}
      ]
    }
  }
}

---

Error Codes

Exit code	Reason
0	Success
1	Company not found, rate limited, timeout, or scraper error

Errors are printed to stderr so stdout always contains clean JSON.

---

Tips for LLM Agents

• Use the all command to fetch everything in a single HTTP request.
• All numeric values are float | null — no string parsing needed.
• Percentage rows (e.g. OPM %) are identified by "unit": "%" on the row.
• Balance Sheet rows include "unit": "liability" or "unit": "asset" to distinguish blocks.
• Cash Flow rows include "unit": "Operating" | "Investing" | "Financing" | "Net".
• The latest field in shareholding always gives the most recent quarter's breakdown.
• peer_comparison.peers is an ordered list (rank 1 = the queried company itself). Each peer's values dict has the same keys as peer_comparison.columns (minus "Name").
• peer_comparison.sector / industry / sub_industry / sub_sub_industry give the full industry hierarchy.
• The columns in the peer table are whichever columns the screener.in user has configured — always check columns before reading values.

---

Responsible Use

• screener.in is a free public service. Please add a delay between requests if running batch jobs.
• Respect robots.txt. Do not use this tool for bulk or automated mass scraping.
• The tool adds a 1-second courtesy delay between retries and caches pages for 5 minutes.

---

Project Structure

screener_cli/
├── cli.py              # Click-based CLI entry point
├── scraper.py          # HTTP fetch, error handling, TTL cache
├── models.py           # Dataclasses for typed output
├── parsers/
│   ├── utils.py        # Generic table parser shared by all sections
│   ├── quarterly.py
│   ├── profit_loss.py
│   ├── balance_sheet.py
│   ├── cash_flow.py
│   ├── ratios.py
│   ├── shareholding.py
│   ├── pros_cons.py
│   └── peers.py        # Peer comparison parser
└── formatters/
    ├── json_fmt.py     # JSON serialiser
    └── text_fmt.py     # Rich terminal renderer
pyproject.toml
requirements.txt

---

License

MIT