Every Screener.in feature, plus offline search, screen intersections, and a local fundamentals mirror no other tool has.
Search any Indian company and pull its full fundamental profile — key metrics, machine-generated pros/cons, quarterly results, P&L, balance sheet, cash flow, ratios, shareholding, peers, and price charts — from the terminal. Sync company pages, screens, and insider trades into a local SQLite mirror, then run cross-company comparisons, quarterly trend flags, screen overlaps, and insider-flow rankings that no single page or API call provides.
Created by @SomSamantray (Som Samantray).
Authentication
Screener.in's public pages (company profiles, screens, sectors, IPO) need no login. Market-pulse pages — latest quarterly results, insider trades, filings — require a free Screener.in account. Run 'screener-pp-cli auth login --chrome' to import your logged-in Chrome session cookie once; the CLI replays it for gated pages.
Quick Start
# Verify connectivity to screener.in
screener-pp-cli doctor
# Find the company ID and symbol
screener-pp-cli company search --q 'Tata Steel' --json
# Pull the full fundamental profile
screener-pp-cli company profile INFY --json
# Run the Bull Cartel screen
screener-pp-cli screens run 1 the-bull-cartel --json
# Spot earnings acceleration or deterioration
screener-pp-cli qtrend INFY --quarters 8 --agent
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
compare — See two to four companies' fundamentals side by side (valuation, margins, growth, insider activity) without tab-switching.
Pick this when an agent needs to decide between candidate stocks on comparable fundamentals instead of fetching pages one at a time.
screener-pp-cli compare TCS HDFCBANK --agent
-
qtrend — Spot whether a company's quarterly profit/sales growth is accelerating or deteriorating, with YOY change and margin drift computed automatically.
Pick this when an agent needs the trend shape of a company's earnings, not just the latest quarter's raw numbers.
screener-pp-cli qtrend INFY --quarters 8 --agent
-
insider-flow — Answer 'who is net buying the most this month?' with per-company insider buy/sell aggregation.
Pick this when an agent needs insider conviction ranked by net value, not a raw list of individual trades.
screener-pp-cli insider-flow --since 30d --top 10 --agent
Cross-entity local queries
-
overlap — Find companies that appear in two or more stock screens in one command, replacing spreadsheet dedup.
Pick this when an agent needs the intersection of multiple screening strategies to find high-conviction candidates.
screener-pp-cli overlap 1 the-bull-cartel 59 magic-formula --agent
-
rank — Re-score a screen's companies with a composite of fundamentals (P/E, ROCE, growth), sorted by what matters to you.
Pick this when an agent should prioritize within a screen by fundamentals or insider conviction rather than the default table order.
screener-pp-cli rank 1 the-bull-cartel --by roce --agent
Recipes
Full company research brief
screener-pp-cli company profile RELIANCE --agent --select top_ratios,analysis,quarterly_results
One command returns the key metrics, pros/cons, and quarterly results as agent-ready JSON
High-conviction screen intersection
screener-pp-cli overlap 1 the-bull-cartel 59 magic-formula --agent
Companies passing both a value formula and a growth screen
Insider conviction ranking
screener-pp-cli insider-flow --since 30d --top 10 --agent
Who's net buying the most this month, ranked by value
Earnings momentum check
screener-pp-cli qtrend INFY --quarters 8 --agent
Is profit growth accelerating or deteriorating over 8 quarters?
Candidate shortlist comparison
screener-pp-cli compare TCS WIPRO HCLTECH --agent --select name,pe,roce,profit_growth
Side-by-side fundamentals for a shortlist, narrowed with --select
Usage
Run screener-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
SCREENER_CONFIG_DIR, SCREENER_DATA_DIR, SCREENER_STATE_DIR, or SCREENER_CACHE_DIR
--home <dir> for this invocationSCREENER_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export SCREENER_HOME=/srv/screener
screener-pp-cli doctor
Under SCREENER_HOME=/srv/screener, the four dirs resolve to /srv/screener/config, /srv/screener/data, /srv/screener/state, and /srv/screener/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"screener": {
"command": "screener-pp-mcp",
"env": {
"SCREENER_HOME": "/srv/screener"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as SCREENER_DATA_DIR overrides an explicit --home for that kind. Use SCREENER_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting SCREENER_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run screener-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
company
Search companies and fetch fundamental profiles
screener-pp-cli company by-id - Fetch a company page by numeric ID (redirects to symbol page)screener-pp-cli company chart - Fetch price/technical chart data for a companyscreener-pp-cli company peers - Fetch peer comparison table for a companyscreener-pp-cli company profile - Fetch the full company profile page (key metrics, analysis, quarterly results, P&L, balance sheet, cash flow, ratios, shareholding, documents)screener-pp-cli company profile-standalone - Fetch standalone (parent-only) company profile pagescreener-pp-cli company search - Search for companies by name or ticker (live autocomplete API)
explore
Browse popular screens and sector categories
screener-pp-cli explore - Browse popular themes, formulas, and sector categories
filings
Market pulse filings hub (requires login)
screener-pp-cli filings - Market Pulse hub: bulk deals, block deals, SAST trades, insider trades
full_text_search
Full-text search across companies and filings (requires login)
screener-pp-cli full-text-search - Full-text search for companies
ipo
Upcoming and recent IPO listings
screener-pp-cli ipo - List upcoming IPOs with subscription status
market
Browse market sectors and industry groups
screener-pp-cli market <sector_path> - List companies in a market sector (e.g. IN08/IN0801/IN080101 = IT - Software)
results
Latest quarterly results (Market Pulse, requires login)
screener-pp-cli results - Latest quarterly results with YOY growth (Sales, EBIDT, Net profit, EPS) and filters
screens
Browse and run stock screening screens
screener-pp-cli screens list - List all stock screening screensscreener-pp-cli screens run - Run a stock screen and get ranked results (CMP, P/E, Mar Cap, Div Yld, NP Qtr, Qtr Profit Var, Sales Qtr, Qtr Sales Var, ROCE)
trades
Market pulse trade activity (requires login)
screener-pp-cli trades - Insider trades (bought/sold/pledge/ESOP) with filters
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
screener-pp-cli recall <query> - Look up cached resources for a query before running discoveryscreener-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)screener-pp-cli learnings list - Inspect taught rowsscreener-pp-cli learnings forget <query> - Undo a teachscreener-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectscreener-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsscreener-pp-cli teach-pattern - Install a query/resource template up frontscreener-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set SCREENER_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of screener-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
screener-pp-cli company search --q example-value
# JSON for scripting and agents
screener-pp-cli company search --q example-value --json
# Filter to specific fields
screener-pp-cli company search --q example-value --json --select id,name,url
# Dry run — show the request without sending
screener-pp-cli company search --q example-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
screener-pp-cli company search --q 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 <field>[,<field>...] 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, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Freshness
This CLI owns bounded freshness for registered store-backed read command paths. In --data-source auto mode, covered commands check the local SQLite store before serving results; stale or missing resources trigger a bounded refresh, and refresh failures fall back to the existing local data with a warning. --data-source local never refreshes, and --data-source live reads the API without mutating the local store.
Set SCREENER_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
screener-pp-cli explorescreener-pp-cli explore getscreener-pp-cli explore listscreener-pp-cli explore searchscreener-pp-cli filingsscreener-pp-cli filings getscreener-pp-cli filings listscreener-pp-cli filings searchscreener-pp-cli full_text_searchscreener-pp-cli full_text_search getscreener-pp-cli full_text_search listscreener-pp-cli full_text_search searchscreener-pp-cli iposcreener-pp-cli ipo getscreener-pp-cli ipo listscreener-pp-cli ipo searchscreener-pp-cli screensscreener-pp-cli screens getscreener-pp-cli screens listscreener-pp-cli screens search
JSON outputs that use the generated provenance envelope include freshness metadata at meta.freshness. This metadata describes the freshness decision for the covered command path; it does not claim full historical backfill or API-specific enrichment.
Health Check
screener-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run screener-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/screener-pp-cli/config.toml; --home, SCREENER_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
SCREENER_SESSION_COOKIE | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, screener-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
screener-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $SCREENER_SESSION_COOKIE
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- results/trades commands redirect to a register page — You are not logged in. Run the 'auth login' command with the Chrome option with your Screener.in session, or 'screener-pp-cli auth status' to check.
- HTTP 429 rate limited — Screener.in throttles bulk access. Wait a few minutes and retry, or use 'sync --since' to cache data locally and query offline.
- HTML table parse produces empty rows — Screener.in occasionally changes table markup. Re-sync with 'screener-pp-cli sync --full' and report the page URL if parsing still fails.
- Commands fail with unexpected errors or empty output — Run 'screener-pp-cli doctor' to verify connectivity and auth, then retry. For auth-gated pages, run the 'auth login' command with the Chrome option to re-import your session.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press