The full history of Foreign Portfolio Investor flows into India, synced locally and queryable offline — something neither NSDL nor CDSL offers today.
NSDL and CDSL publish authoritative FPI investment data, but only as ASP.NET report pages with a client-side Excel export button — no API, no bulk historical download, no scriptable access. fpi-india syncs the full net-investment series back to 1992-93, plus AUC, sector rotation, trade data, and the FPI registry, into a local SQLite database you can query, trend, and pipe.
Quick Start
# confirm the CLI can reach NSDL before syncing
fpi-india-pp-cli doctor --dry-run
# pull the full historical FY series (1992-93-to-present) into local SQLite
fpi-india-pp-cli sync --resources net_investment --full
# see the synced historical equity flow series
fpi-india-pp-cli net-investment fy --json
# compare this year's flow against last year, computed locally
fpi-india-pp-cli net-investment yoy --asset equity --year 2024 --json
# see the current buying/selling streak, a computation no source page offers
fpi-india-pp-cli net-investment streaks --asset equity --json
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
net-investment yoy — See this year's FPI net flow next to the same period last year, delta computed automatically.
Reach for this when a request compares FPI flow across two adjacent years instead of listing raw rows.
fpi-india-pp-cli net-investment yoy --asset equity --year 2024 --json
-
sector rotation — Rank which sectors saw the biggest FPI inflow/outflow swing between the two most recent synced periods.
Use this for 'what sector are FPIs rotating into/out of' instead of a single-period sector snapshot.
fpi-india-pp-cli sector rotation --top 5 --period latest --json
-
limits utilization — See what percentage of the regulatory FPI investment cap a sector or debt category has used.
Use this to flag sectors approaching a regulatory FPI cap, which can trigger a trading halt.
fpi-india-pp-cli limits utilization --sector Banking --json
-
net-investment streaks — See how many consecutive fortnights/years FPIs have been net buyers or sellers, and the most recent flip.
Use this for 'how many periods in a row' questions instead of scanning raw historical rows.
fpi-india-pp-cli net-investment streaks --asset equity --json
-
auc trend — Track how a country's or category's share of assets under custody has changed across synced snapshots.
Use this once at least two snapshots are synced to see custody-share direction, not a single-point value.
fpi-india-pp-cli auc trend --by country --country Mauritius --json
-
net-investment extremes — Find the largest single-period FPI inflows or outflows across the full 1992-93-to-present series.
Use this for 'biggest ever' / superlative questions about historical FPI flow.
fpi-india-pp-cli net-investment extremes --asset equity --top 10 --json
-
net-investment trend — See the rolling growth-rate and direction of FPI net flow over a window of recent periods.
Use this for a derived growth-rate/direction view, not raw historical rows (use 'net-investment fy'/'cy'/'quarterly'/'latest' for those).
fpi-india-pp-cli net-investment trend --asset equity --period fy --window 12 --json
Reachability mitigation
-
cdsl diff — Compare NSDL's and CDSL's figures for the same date and flag any mismatch.
Use this to cross-check the two Indian depositories' published figures for the same date.
fpi-india-pp-cli cdsl diff --date 09072026 --json
Recipes
Full historical equity flow series
fpi-india-pp-cli net-investment fy --json --select period,total,cumulative_total
Narrow a 30+ year series down to just the fields needed for a chart or note.
This fortnight vs last year, same fortnight
fpi-india-pp-cli net-investment yoy --asset equity --year 2024
The Monday-morning commentary workflow: one command instead of loading two pages and subtracting by hand.
What sector is money rotating into
fpi-india-pp-cli sector rotation --top 5 --period latest
Ranks period-over-period sector deltas instead of a single period's absolute figures.
Is any sector near its FPI investment cap
fpi-india-pp-cli limits utilization --sector Banking
Joins synced limits against synced investment totals to compute percent-of-cap used.
Biggest FPI outflow ever recorded
fpi-india-pp-cli net-investment extremes --asset equity --top 10
Deterministic ranking over the full synced history for journalist-style superlative questions.
Usage
Run fpi-india-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 such as data.db |
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:
FPI_INDIA_CONFIG_DIR, FPI_INDIA_DATA_DIR, FPI_INDIA_STATE_DIR, or FPI_INDIA_CACHE_DIR
--home <dir> for this invocationFPI_INDIA_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 FPI_INDIA_HOME=/srv/fpi-india
fpi-india-pp-cli doctor
Under FPI_INDIA_HOME=/srv/fpi-india, the four dirs resolve to /srv/fpi-india/config, /srv/fpi-india/data, /srv/fpi-india/state, and /srv/fpi-india/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"fpi-india": {
"command": "fpi-india-pp-mcp",
"env": {
"FPI_INDIA_HOME": "/srv/fpi-india"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as FPI_INDIA_DATA_DIR overrides an explicit --home for that kind. Use FPI_INDIA_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting FPI_INDIA_HOME does not move files back to platform defaults, and doctor cannot find files 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. Run fpi-india-pp-cli doctor --fail-on warn to check path warnings in automation.
Commands
auc
FPI assets under custody (AUC), by country and by category
fpi-india-pp-cli auc category - FPI AUC category-wise datafpi-india-pp-cli auc country - FPI AUC country-wise data (top 10 countries)
cdsl_reports
CDSL daily FPI snapshot publication index and dated XLS snapshot download
fpi-india-pp-cli cdsl-reports listing - Index page listing recent dated FPI snapshot XLS filesfpi-india-pp-cli cdsl-reports snapshot - Dated daily FPI snapshot file (date format DDMMYYYY, e.g. 09072026)
limits
Per-company (ISIN) foreign investment limits: NRI limit %, FPI limit %, sectoral cap %, and current monitored FPI holding count
fpi-india-pp-cli limits - Per-ISIN foreign investment limit monitoring data
net_investment
Historical FPI net-investment flows by asset class (equity, debt, hybrid, mutual funds, AIF), financial year and calendar year
fpi-india-pp-cli net-investment cy - Calendar-year FPI net-investment series, with monthly breakdown when a specific year is requestedfpi-india-pp-cli net-investment fy - Full financial-year FPI net-investment series (1992-93 to present)fpi-india-pp-cli net-investment latest - Latest fortnight FPI net-investment snapshotfpi-india-pp-cli net-investment quarterly - Quarterly FPI net-investment details (calendar year)
registry
Registered FPI list, registration category counts, and DDP pendency
fpi-india-pp-cli registry categories - FPI category-wise registration countsfpi-india-pp-cli registry list - List of registered FPIs/FIIsfpi-india-pp-cli registry pendency - DDP-wise pendency of FPI applications
sector
Fortnightly sector-wise FPI investment data
fpi-india-pp-cli sector - Fortnightly sector-wise FPI investment activity
trades
Trade-wise FPI equity and debt data
fpi-india-pp-cli trades debt - Trade-wise debt data of FPIfpi-india-pp-cli trades equity - Trade-wise equity data of FPI
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.
fpi-india-pp-cli recall <query> - Look up cached resources for a query before running discoveryfpi-india-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)fpi-india-pp-cli learnings list - Inspect taught rowsfpi-india-pp-cli learnings forget <query> - Undo a teachfpi-india-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectfpi-india-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsfpi-india-pp-cli teach-pattern - Install a query/resource template up frontfpi-india-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set FPI_INDIA_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of fpi-india-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)
fpi-india-pp-cli limits --action GetFilmReport_Detail --u-name example-resource
# JSON for scripting and agents
fpi-india-pp-cli limits --action GetFilmReport_Detail --u-name example-resource --json
# Filter to specific fields
fpi-india-pp-cli limits --action GetFilmReport_Detail --u-name example-resource --json --select id,name,status
# Dry run — show the request without sending
fpi-india-pp-cli limits --action GetFilmReport_Detail --u-name example-resource --dry-run
# Agent mode — JSON + compact + no prompts in one flag
fpi-india-pp-cli limits --action GetFilmReport_Detail --u-name example-resource --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 id,name 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, 5 API error, 7 rate limited, 10 config error.
Health Check
fpi-india-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Run fpi-india-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ``; --home, FPI_INDIA_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- sync returns 0 rows for a report — NSDL occasionally changes a report's table id after a site update; run
fpi-india-pp-cli doctor --json to confirm the page is reachable, then check for a generator update.
cdsl-reports snapshot returns stale or missing dates — that command downloads CDSL's legacy rolling-window daily .xls file; older dates will not be available from it even after sync. For real granular daily data (parsed, not a binary download), use net-investment latest/monthly/archive (NSDL) or cdsl-reports daily/monthly (CDSL) instead — archive reaches arbitrary historical dates, the others only the current period. See Known Gaps below.
Known Gaps
Disclosed, deliberate scope reductions — genuine engineering-surface limits, not corner-cutting:
registry list (raw FPI/FII name list) — RegisteredFIISAFPI.aspx is a search form requiring an ASP.NET WebForms VIEWSTATE/EVENTVALIDATION POST replay, a different engineering surface from every other GET-based report this CLI uses. Not synced; the command remains present but returns live-fetch results only. registry categories and registry pendency are unaffected (plain GET). (net-investment archive shows this same class of VIEWSTATE POST form is scriptable when the target page needs it — registry list's form has more fields and validation to reverse-engineer, which is why it's still a disclosed gap rather than done.)cdsl-reports snapshot — CDSL's dated snapshot files (/downloads/Publications/Latest/latest_{date}.xls) are legacy binary XLS (OLE2 Compound Document format), not HTML or JSON, so this command downloads the raw file rather than parsing it. Real parsed daily/monthly CDSL data is available via cdsl-reports daily/monthly instead.trades equity/trades debt column naming — the source table has 3+ levels of header nesting (year groups × month sub-columns); the generic composite-name heuristic produces functional but imperfectly-labeled columns for this specific report.