--- name: pp-nccpl description: "Pakistan's clearing-layer data as a local research panel with a coverage audit and an arithmetic self-check, not another dashboard. Trigger phrases: `foreign investor flows on the PSX`, `FIPI and LIPI for last week`, `which sectors did foreigners buy`, `short interest on a Pakistani stock`, `free float for a PSX symbol`, `MTS open positions`, `use nccpl`, `run nccpl`." author: "qazmataz" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - nccpl-pp-cli install: - kind: go bins: [nccpl-pp-cli] module: github.com/mvanhorn/printing-press-library/library/payments/nccpl/cmd/nccpl-pp-cli --- # NCCPL — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `nccpl-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install nccpl --cli-only ``` 2. Verify: `nccpl-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/payments/nccpl/cmd/nccpl-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. NCCPL publishes the only per-symbol leverage, short-interest and free-float data in the Pakistani market - once, behind Cloudflare, one date at a time, with no export. Every tool built on it renders a chart and throws the history away. This one keeps it: sync backfills a local SQLite panel, panel emits it in the shape a regression consumes, coverage tells you exactly which sessions are missing, and verify proves each date against NCCPL's own arithmetic identities before you trust it. ## When to Use This CLI Reach for this CLI when you need Pakistani market data that sits below the exchange feed: who bought and sold by investor class, how much leverage and short interest is open against a symbol, what a symbol's free float and VAR margin are, and how trade volume reconciles against settlement. It is built for assembling history into a local panel and handing that panel to a model, so prefer it whenever the question spans more than one date. It is also the right tool for auditing data you already pulled, because it can prove a date against NCCPL's own arithmetic identities and tell you which sessions are missing. ## Anti-triggers Do not use this CLI for: - Do not use this CLI for live or intraday prices, quotes, or index levels - NCCPL publishes post-settlement data once per session, not a market feed. - Do not use this CLI for company fundamentals, earnings, announcements or corporate actions; it is a clearing house, not a filings source. - Do not use this CLI to place, modify or settle trades - every endpoint it reaches is read-only market information. - Do not use this CLI to compute a regression or backtest result; export a panel and run the analysis in your own research code. - Do not expect deep history on every resource - some NCCPL surfaces are near-dormant, so run coverage before assuming an archive exists. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Research-grade integrity - **`verify`** — Prove a date's flow numbers are internally consistent before they reach a regression. _Reach for this before feeding any NCCPL date into a model; a date that fails an invariant is corrupt input, not a weak signal._ ```bash nccpl-pp-cli verify --from 2026-08-01 --to 2026-09-04 --agent ``` - **`coverage`** — List which sessions are missing per resource, how stale each one is, and how wide each date's data actually is. _Use this as a pipeline pre-flight - it exits non-zero on a gap, so a scheduled research job fails loudly instead of silently treating a missing session as a zero. Re-syncing a date replaces it rather than adding to it: a stored settlement date always mirrors the last snapshot fetched for it, so if NCCPL revises a date and drops symbols the next sync removes them and the store never serves a row the source stopped publishing. coverage row_count therefore always equals the number of observations actually stored, and the audit can never disagree with the data it audits. One deliberate exception: a fetch returning zero rows for a date that already holds rows does NOT delete them, because an empty response and a transient failure look identical from here; the next non-empty fetch mirrors the date correctly._ ```bash nccpl-pp-cli coverage --resources fipi,lipi,var-margins --exit-code --agent ``` - **`contract-check`** — Assert every endpoint family still answers correctly for a date it just reported as its own latest. _Run this when results look empty - it separates an expired session or a changed request contract from a genuine no-data day._ ```bash nccpl-pp-cli contract-check --agent ``` ### Local history that compounds - **`panel`** — Emit any synced resource as a tidy long-format panel, with gaps marked rather than filled. _This is the handoff from CLI to research store - it is the shape a regression consumes, and the observed_at column is what makes a flow number admissible as an ex-ante input._ ```bash nccpl-pp-cli panel --resource fipi --from 2015-12-09 --to 2026-09-04 --agent ``` - **`universe`** — Reconstruct which symbols were listed and clearing-eligible on any past date. _Use this to state a screen's universe width in genuinely live names, and as a second opinion that can disagree with a price-staleness filter for reasons that filter cannot move for._ ```bash nccpl-pp-cli universe --on 2019-03-15 --agent ``` - **`risk-changes`** — Date every step change in a symbol's free float, VAR margin and haircut. _Free float is the input a cap-weighted cross-section needs and no other public Pakistani source publishes it daily._ ```bash nccpl-pp-cli risk-changes --since 30d --field free_float --agent ``` ### Cross-market joins - **`leverage`** — Join MTS, MFS and MSF open positions with SLB net open position into one per-symbol cross-section. _SLB net open position is the closest thing this market has to published short interest; pair it with MTS and MFS open interest to see leverage building in a name before a forced release._ ```bash nccpl-pp-cli leverage --from 2026-08-01 --to 2026-09-04 --agent ``` ### Reachability mitigation - **`flows`** — Fetch daily FIPI/LIPI sector flows into the local store without a browser. _This is the one NCCPL dataset obtainable unattended, so it is what a scheduled daily job can actually collect._ ```bash nccpl-pp-cli flows --from 2026-08-01 --to 2026-09-04 --agent ``` - **`ingest`** — Load NCCPL responses captured through your own browser into the same local store. _Reach for this when a dataset is gated: export a HAR from a normal browsing session and every other command works on it unchanged. Bodies can also be piped in directly with --stdin (pbpaste | nccpl-pp-cli ingest --stdin --resource var-margins --date 2026-09-04), so a single copied response never needs a temp file. Nothing unidentifiable is stored: a HAR entry is only ingested when it was served by nccpl.com.pk or a subdomain over https, and a response body must carry either the documented envelope key for the resource or exactly one of the API's own other envelope names. An all-traffic capture routinely holds other origins -- a proxy, a mock, a local dev server on the same path -- and those are refused and listed under skipped with a reason, never filed under a guess._ ```bash nccpl-pp-cli ingest capture.har --agent ``` - **`capture`** — Fetch the gated NCCPL datasets through a controlled browser and store them locally; opt in with --launch, and add --headless to run with no window. _This is the only route to per-symbol free float, VAR margins, leverage positions and settlement data; every other command then reads them from the local store with no browser involved. With --headless no window appears and the run is unattended, so a scheduled job can keep the gated datasets current; Chrome must be installed because the clearance cannot be replayed by any non-browser HTTP client._ ```bash nccpl-pp-cli capture --resources var-margins --latest-only --agent ``` ## HTTP Transport This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls. ## Discovery Signals This CLI was generated with browser-observed traffic context. - Capture coverage: 51 API entries from 204 total network entries - Protocols: rest_json (75% confidence), html_scrape (55% confidence) - Generation hints: browser_http_transport, requires_protected_client - Candidate command ideas: create_data_by_date_range — Derived from observed POST /api/graph-data/data-by-date-range traffic.; create_rum — Derived from observed POST /cdn-cgi/rum traffic.; list_latest_data — Derived from observed GET /api/graph-data/latest-data traffic.; list_latest_date — Derived from observed GET /api/financiers-financees/latest-date traffic. - Caveats: empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.; empty_payload: API-looking request returned an empty or null payload; schema confidence is weak. ## Command Reference **fipi** — Foreign Investors Portfolio Investment (FIPI) net flows by investor class and market segment. - `nccpl-pp-cli fipi data` — Foreign Investors Portfolio Investment (FIPI) net flows by investor class and market segment. Date range. - `nccpl-pp-cli fipi latest-date` — Most recent publication date available for fipi. Needs Cloudflare clearance only; no CSRF or session. **fipi-normal** — FIPI buy/sell volume and value by client type and market type for one date. - `nccpl-pp-cli fipi-normal data` — FIPI buy/sell volume and value by client type and market type for one date. Single settlement date. - `nccpl-pp-cli fipi-normal latest-date` — Most recent publication date available for fipi-normal. Needs Cloudflare clearance only; no CSRF or session. **fipi-sector** — FIPI net flows broken out by market sector. - `nccpl-pp-cli fipi-sector data` — FIPI net flows broken out by market sector. Date range. - `nccpl-pp-cli fipi-sector latest-date` — Most recent publication date available for fipi-sector. Needs Cloudflare clearance only; no CSRF or session. **lipi** — Local Investors Portfolio Investment (LIPI) net flows by investor class and market segment. - `nccpl-pp-cli lipi data` — Local Investors Portfolio Investment (LIPI) net flows by investor class and market segment. Date range. - `nccpl-pp-cli lipi latest-date` — Most recent publication date available for lipi. Needs Cloudflare clearance only; no CSRF or session. **lipi-normal** — LIPI buy/sell volume and value by client type and market type for one date. - `nccpl-pp-cli lipi-normal data` — LIPI buy/sell volume and value by client type and market type for one date. Single settlement date. - `nccpl-pp-cli lipi-normal latest-date` — Most recent publication date available for lipi-normal. Needs Cloudflare clearance only; no CSRF or session. **lipi-sector** — LIPI net flows broken out by market sector. - `nccpl-pp-cli lipi-sector data` — LIPI net flows broken out by market sector. Date range. - `nccpl-pp-cli lipi-sector latest-date` — Most recent publication date available for lipi-sector. Needs Cloudflare clearance only; no CSRF or session. **market** — Market-wide traded value and volume series. - `nccpl-pp-cli market latest` — Most recent market-wide traded value or volume series. Needs Cloudflare clearance only. - `nccpl-pp-cli market range` — Market-wide traded value or volume series over an explicit date range. **mfs** — Murabaha Share Financing (MFS) open positions per symbol, with free-float percentages. - `nccpl-pp-cli mfs data` — Murabaha Share Financing (MFS) open positions per symbol, with free-float percentages. Single settlement date. - `nccpl-pp-cli mfs latest-date` — Most recent publication date available for mfs. Needs Cloudflare clearance only; no CSRF or session. **mfs-top** — Top 15 MFS financee / financier pairs. - `nccpl-pp-cli mfs-top data` — Top 15 MFS financee / financier pairs. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli mfs-top latest-date` — Most recent publication date available for mfs-top. Needs Cloudflare clearance only; no CSRF or session. **msf** — Margin Sharia Financing (MSF) open positions per symbol. - `nccpl-pp-cli msf data` — Margin Sharia Financing (MSF) open positions per symbol. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli msf latest-date` — Most recent publication date available for msf. Needs Cloudflare clearance only; no CSRF or session. **msf-top** — Top 15 MSF buyer / seller pairs. - `nccpl-pp-cli msf-top data` — Top 15 MSF buyer / seller pairs. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli msf-top latest-date` — Most recent publication date available for msf-top. Needs Cloudflare clearance only; no CSRF or session. **mts** — Margin Trading System (MTS) open positions per symbol. - `nccpl-pp-cli mts data` — Margin Trading System (MTS) open positions per symbol. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli mts latest-date` — Most recent publication date available for mts. Needs Cloudflare clearance only; no CSRF or session. **mts-financiers** — Count of MTS financiers and financees per symbol. - `nccpl-pp-cli mts-financiers data` — Count of MTS financiers and financees per symbol. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli mts-financiers latest-date` — Most recent publication date available for mts-financiers. Needs Cloudflare clearance only; no CSRF or session. **mts-force-release** — MTS force-release volume and value by date. - `nccpl-pp-cli mts-force-release data` — MTS force-release volume and value by date. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli mts-force-release latest-date` — Most recent publication date available for mts-force-release. Needs Cloudflare clearance only; no CSRF or session. **mts-refinanced** — MTS amount released versus amount refinanced. - `nccpl-pp-cli mts-refinanced data` — MTS amount released versus amount refinanced. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli mts-refinanced latest-date` — Most recent publication date available for mts-refinanced. Needs Cloudflare clearance only; no CSRF or session. **mts-top-financiers** — Top 15 MTS financier / financee pairs. - `nccpl-pp-cli mts-top-financiers data` — Top 15 MTS financier / financee pairs. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli mts-top-financiers latest-date` — Most recent publication date available for mts-top-financiers. Needs Cloudflare clearance only; no CSRF or session. **settlement-cm** — Trade versus settlement volume and value, clearing-member-wise, per symbol. - `nccpl-pp-cli settlement-cm data` — Trade versus settlement volume and value, clearing-member-wise, per symbol. Single settlement date. - `nccpl-pp-cli settlement-cm latest-date` — Most recent publication date available for settlement-cm. Needs Cloudflare clearance only; no CSRF or session. **settlement-uin** — Trade versus settlement volume and value, UIN-wise, per symbol. - `nccpl-pp-cli settlement-uin data` — Trade versus settlement volume and value, UIN-wise, per symbol. Single settlement date. - `nccpl-pp-cli settlement-uin latest-date` — Most recent publication date available for settlement-uin. Needs Cloudflare clearance only; no CSRF or session. **slb** — Securities Lending and Borrowing (SLB) open positions per symbol. - `nccpl-pp-cli slb data` — Securities Lending and Borrowing (SLB) open positions per symbol. Single settlement date. - `nccpl-pp-cli slb latest-date` — Most recent publication date available for slb. Needs Cloudflare clearance only; no CSRF or session. **tfc** — Unlisted Term Finance Certificate (TFC) transactions. - `nccpl-pp-cli tfc data` — Unlisted Term Finance Certificate (TFC) transactions. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli tfc latest-date` — Most recent publication date available for tfc. Needs Cloudflare clearance only; no CSRF or session. **var-margins** — Value-at-Risk margin, haircut and free float per symbol. - `nccpl-pp-cli var-margins data` — Value-at-Risk margin, haircut and free float per symbol. Single settlement date. The 'date' field must be YYYY-MM-DD. - `nccpl-pp-cli var-margins latest-date` — Most recent publication date available for var-margins. Needs Cloudflare clearance only; no CSRF or session. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash nccpl-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Backfill the foreign-flow archive and check it landed ```bash nccpl-pp-cli sync --resources fipi,lipi --full && nccpl-pp-cli coverage --resources fipi,lipi --exit-code ``` Fills the local store as far back as NCCPL serves, then fails non-zero if any session is missing so a scheduled job cannot silently proceed on a hole. ### Emit a regression-ready flow panel with only the fields a model needs ```bash nccpl-pp-cli panel --resource fipi --from 2015-12-09 --to 2026-09-04 --agent --select date,metric,value,observed_at ``` Long-format rows with the vintage stamp that establishes ex-ante availability, narrowed to four columns so an agent does not parse the whole payload. ### Find every symbol whose free float stepped this quarter ```bash nccpl-pp-cli r