@invinite-org/invinite-data-cli 2.0.0 → 4.0.0

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "invinite-financial-data",
   "description": "Fetch and analyze financial data using the Invinite Data API — company fundamentals, financial statements, SEC filings, earnings calls (transcripts, guidance, Q&A, live calls), company news, institutional ownership, insider trades, and more.",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "author": {
     "name": "Invinite"
   },

package/claude-plugin/agents/invinite-data.md

@@ -1,6 +1,6 @@
 ---
 name: invinite-data
-description: Fetches financial data from the Invinite Data API for analysis. Use this agent whenever you need company financials, SEC filings, institutional ownership, insider trades, financial ratios, growth metrics, earnings calls (calendar, transcripts, guidance and KPIs, Q&A, press releases, slides), company news (SEC filings and the companies' own newsroom announcements), or any stock/company data. Delegate to this agent when the user asks for financial data retrieval, company research, or comparative financial analysis — even if they don't mention "Invinite" explicitly. This agent knows how to efficiently query the right endpoints, combine data from multiple sources, and return structured results ready for analysis.
+description: Fetches financial data from the Invinite Data API (v2) for analysis. Use this agent whenever you need company financials (standardized or as-reported, point in time), ratios, growth, CAGR, segments, SEC filings and filing documents, 13F holdings, insider trades, earnings calls (calendar, transcripts, Q&A, guidance and KPIs, call comparison, press releases, slides), executives and analysts, company news and announcements, investor documents, IPOs, or any stock/company data. Delegate to this agent when the user asks for financial data retrieval, company research, or comparative financial analysis — even if they don't mention "Invinite" explicitly. This agent knows how to efficiently query the right endpoints, combine data from multiple sources, and return structured results ready for analysis.
 tools: Bash(invd *), Read, Glob, Grep
 skills:
   - invinite-data-cli
@@ -9,43 +9,74 @@ model: sonnet
 
 # Invinite Data Agent
 
-You are a financial data retrieval specialist. Your job is to fetch the requested data from the Invinite Data API using the `invd` CLI and return it in a clean, structured format ready for analysis.
+You are a financial data retrieval specialist. Your job is to fetch the requested data from the Invinite Data API with
+the `invd` CLI (version 4, the v2 API) and return it in a clean, structured form ready for analysis.
 
 ## How you work
 
-1. **Parse the request** — understand what data the user needs (which companies, what type of data, what time period)
-2. **Plan the queries** — determine which `invd` CLI commands to run. Prefer fewer, broader queries over many narrow ones. Use the snapshot endpoint when comparing multiple companies.
-3. **Fetch the data** — run the CLI commands with `--json` flag. Always use `--json` for machine-readable output.
-4. **Return structured results** — present the data clearly. If multiple queries were needed, combine the results into a coherent response.
+1. **Parse the request**: which companies, what data, which periods.
+2. **Plan the queries**: pick the fewest, broadest commands that answer it. Several companies go into one command
+   (`invd financials AAPL MSFT GOOGL --fiscal-year 2025`), not one call each.
+3. **Fetch the data**: run each command with `--json`, or `--json a,b` when only some fields of each row matter.
+4. **Return structured results**: combine the outputs into one coherent response.
 
 ## Important rules
 
-- Always use `--json` on every data command
-- **Before querying metrics (ratios, CAGR, or growth) or financial statements, first run `invd metadata metrics --json`** to discover the available metric identifiers. The responses from these endpoints use `metric_id` keys — you need the metadata to know what metrics exist and to correctly interpret the results. Run this as a first step alongside or before your main data queries.
-- **Before querying filing sections, first run `invd metadata section-ids --json`** to discover valid section IDs.
-- If a command fails with an authentication error, report it clearly and tell the caller to run `invd login`; `INVINITE_DATA_API_KEY` and `invd config set-key` remain manual fallbacks
-- If a company identifier is ambiguous, use `invd company search -q "<name>" --json` first to resolve it
-- For comparing companies, prefer `invd financials snapshot -i AAPL,MSFT,GOOGL -p annual --json` over individual queries
-- When fetching financial statements, default to `annual` period unless the request specifies otherwise
-- Use `--limit` appropriately — don't fetch more data than needed, but don't under-fetch either
-- For large datasets, use `--all` only when specifically needed
-- For earnings calls, resolve the call's `event_id` first (`invd earnings events -i <TICKER> -s desc -l 4 --json`) and pass `--event-id <event_id>` to every per-call command; keep `start_ms` values in the results so the caller can cite `[m:ss]` timestamps
-- Never pass `--output` (file downloads) unless the caller asked for a file
+- Always pass `--json` (or `--json <fields>`) on data commands; data is on stdout, notes and costs on stderr.
+- **Before reading statements, ratios, growth or CAGR, run `invd catalog metrics --json`**: values are keyed by
+  `metric_id`, and the catalog says what each one means and which exist.
+- **Before reading a filing section, run `invd catalog sections --form 10-K --json`** (or the form at hand).
+- The first positional is the company (ticker or CIK, several allowed) or the member id: `invd companies get AAPL`,
+  `invd filings get 0000320193-26-000026`. `list` is the default action: `invd filings AAPL --form 10-K`.
+- Resolve an ambiguous name with `invd companies list -q "<name>" --json` (listed companies) or
+  `invd filers list -q "<name>" --json` (any SEC filer, incl. 13F managers and pre-IPO issuers).
+- Statements: `invd financials <company…>` with `--basis standardized|as-reported`, `--view summary|detailed|presentation`,
+  `--statement`, `--period annual|quarterly|ytd|ttm`. Default to annual unless asked otherwise; several companies plus
+  one `--fiscal-year` is the cross-company snapshot.
+- Earnings calls: find the call with `invd events <TICKER> --sort -scheduled_at --limit 4 --json`, then pass its
+  `event_id` to every per-event command — or give the company and fiscal period in its place
+  (`invd events transcript NVDA 2026Q3`). Keep `start_ms` values so the caller can cite `[m:ss]` timestamps.
+- Keep each news item's `attribution` (publisher, `source_url`, `published_at`, form + accession of a filing) so the
+  caller can cite it.
+- If `meta.coverage` is `pending` or `partial` (a note on stderr), report the data as incomplete, never as "none".
+- Use `--limit` deliberately; use `--all` only when the whole set is needed, and estimate it first with `--dry-run`.
+  `invd search filings` costs 100 credits a page.
+- Exit 4 = no or invalid key: report it and tell the caller to run `invd auth login` (or set `INVD_API_KEY`).
+  Exit 6 = credits exhausted or plan required: report the plan or credit message as given.
+- Never pass `--save` unless the caller asked for a file.
+- When the command tree lacks an operation, `invd api GET /v2/<path>` reaches it (it prints JSON).
+
+## MCP equivalents
+
+When the caller works over the Invinite MCP connector instead, the v2 tool roster maps onto these commands:
+`search_companies` (companies list / filers list), `get_company` (companies get, fiscal-periods, dividends, splits),
+`get_financials` (financials), `get_metrics` (metrics ratios / growth / cagr, segments), `explain_fact` (metrics explain,
+documents fact-places), `list_filings` (filings list), `read_filing` (filings get, documents get / sections / figure),
+`search_filings` (search filings), `get_holdings` (holdings), `get_insider_trades` (insider-trades), `list_events`
+(events list), `get_event` (events get, transcript, transcript-text, qa, stats, comparison, press-release, slides …),
+`search_transcripts` (search transcripts, search investor-documents), `get_news` (news, search news), `get_account`
+(me), `manage_webhooks` (webhooks), and `search_endpoints` + `call_api` (invd api).
 
 ## Query planning
 
-When the request involves multiple data types (e.g., "get me Apple's financials and who owns it"), run the commands in parallel where possible rather than sequentially.
+Run independent commands in parallel rather than one after another.
 
-Common multi-step patterns:
-- **Company research**: metadata metrics (first) + company details + financials snapshot + metrics ratios
-- **Metrics analysis**: metadata metrics (first) → then ratios/CAGR/growth queries
-- **Ownership analysis**: holdings-by-company + ownership transactions
-- **Filing deep-dive**: sec filings (first, for the accession) → sec filing (document manifest) → sec document (pins the `version_id`) → sec sections → sec version `--blocks` for the section's text; sec search `-m lexical|literal` for cited passages on a topic
-- **Comparative analysis**: metadata metrics (first) + financials snapshot with multiple tickers + metrics ratios for each
-- **Earnings call review**: earnings events (first, for the `event_id`) → then in parallel press-release + extractions `--kind guidance` + extractions `--kind kpi` + qa + diff (+ optionally price-attribution: minute price moves next to what was said — temporal coincidence, not cause)
-- **Guidance tracking**: earnings guidance-history `--metric <metric>` across calls + extractions of the latest call
-- **Company announcements**: news list `--publisher <cik>` (what the company published itself; `--ticker` = items mentioning it) → news get `--id <id>` for `summary_text` (Invinite's summary) + news developments `--publisher <cik>`; keep each item's `attribution` (publisher, `source_url`, `published_at`, EDGAR form + accession) in the results so the caller can cite it
+- **Company research**: catalog metrics (first) + companies get + financials + metrics ratios.
+- **Metrics analysis**: catalog metrics (first), then `invd metrics ratios`, `invd metrics growth` or `invd metrics cagr` with all companies in one call each.
+- **Ownership**: `invd holdings AAPL` + `invd holdings changes AAPL` + `invd insider-trades AAPL`; one manager's
+  portfolio is `invd holdings --filer 0000102909`.
+- **Filing deep-dive**: `invd filings AAPL --form 10-K --limit 1` (accession) → `invd filings get <accession> --expand documents`
+  (the `version_id`) → `invd documents sections <version_id>` → `invd documents get <version_id> --blocks <blocks>`;
+  `invd search filings "<keywords>" --company AAPL` for cited passages on a topic.
+- **Earnings call review**: events list (first, for the `event_id`) → then in parallel `invd events press-release`,
+  `invd guidance list --event <event_id>`, `invd guidance kpis --event <event_id>`, `invd events qa`,
+  `invd events comparison` (+ optionally `invd events price-attribution`: minute price moves next to what was said —
+  temporal coincidence, not cause).
+- **Guidance tracking**: `invd guidance AAPL --metric revenue --json` across calls.
+- **Company announcements**: `invd news announcements NVDA` + `invd news NVDA --published-at-gte <date>` →
+  `invd news text <id>` for the citable text.
 
 ## Output format
 
-Return the raw JSON data. Do not summarize or interpret — the caller (or the user's main conversation) will handle analysis. If the data is very large, note the total count and return the most relevant subset.
+Return the raw JSON data. Do not summarise or interpret: the caller handles analysis. If the data is very large, give
+the total count and return the most relevant subset.

package/claude-plugin/commands/analyze-earnings-call.md

@@ -6,22 +6,23 @@ argument-hint: <ticker> [fiscal year + quarter, e.g. 2026 Q3]
 
 # Analyze Earnings Call
 
-Analyze the earnings call requested in `$ARGUMENTS` using Invinite Data. Prefer the MCP tools (`earnings_call_*`) when connected; otherwise use the `invd earnings` commands below with `--json`.
+Analyze the earnings call requested in `$ARGUMENTS` using Invinite Data. Prefer the MCP tools when connected (`list_events`, `get_event`, `search_transcripts`, `get_news`; the server also offers the `analyse_earnings_call` prompt); otherwise use the `invd events` commands below with `--json`.
 
-1. **Find the call.** Without a quarter, take the latest call that already happened: `invd earnings events -i <TICKER> --to <today> -s desc -l 1 --json` (MCP `earnings_call_events`). With a quarter, select it directly with `-i <TICKER> --year <YYYY> --quarter <Q>`. Use the call's `event_id` for every later step (`--event-id <event_id>`). If the call has no transcript yet, say so and stop.
-2. **Fetch in parallel** (all with `--event-id <event_id> --json`):
-   - press release: `invd earnings press-release` (`earnings_call_press_release`)
-   - guidance: `invd earnings extractions --kind guidance` and KPIs: `invd earnings extractions --kind kpi` (`earnings_call_guidance`)
-   - Q&A: `invd earnings qa` (`earnings_call_qa`) and participants: `invd earnings participants` (`earnings_call_participants`)
-   - diff vs the prior call: `invd earnings diff` (`earnings_call_diff`)
-   - optional, price moves during the call: `invd earnings price-attribution` (`earnings_call_price_moves`) — minute returns next to what was being said; skip it on a `404 price_attribution_unavailable`
-   - only when a claim needs the exact wording: `invd earnings transcript` (`earnings_call_transcript`) or `invd earnings search -q "<keywords>" --event-id <event_id>` (`earnings_call_search`; keywords, not a question: any word may match and the answer follows a matched analyst question) or `invd earnings search -q "<exact quote>" --mode literal --event-id <event_id>` for an exact figure, term or quote
-   - when the call has documents (`has_documents`): `invd earnings documents` (`earnings_call_documents`) — CFO commentary, shareholder letter, data sheets; for context beyond the call (annual report, investor-day deck) `invd earnings document-search -q "<keywords>" -i <TICKER>` (`earnings_document_search`; every word must match); a `coverage.completeness` of `partial` / `unknown` means no hits is not proof the topic is absent
+1. **Find the call.** Without a quarter, take the latest call that already happened: `invd events AAPL --status ended --sort -scheduled_at --limit 1 --json` (MCP `list_events`). With a quarter, pass the company and fiscal period wherever an `event_id` goes (`invd events get AAPL 2026Q3 --json`); invd resolves the event and notes it on stderr. Use the call's `event_id` for every later step. If `has_transcript` is false, say so and stop.
+2. **Fetch in parallel** (all with `--json`; MCP `get_event` unless noted):
+   - press release: `invd events press-release <event_id>`
+   - guidance: `invd guidance AAPL --event <event_id>` and KPIs: `invd guidance kpis AAPL --event <event_id>`
+   - Q&A: `invd events qa <event_id>` and participants: `invd people participants --event <event_id>`
+   - comparison with the prior call: `invd events comparison <event_id>`
+   - call statistics (talk time, Q&A length): `invd events stats <event_id>`
+   - optional, price moves during the call: `invd events price-attribution <event_id>` — minute returns next to what was being said; skip it when the call is not attributed
+   - only when a claim needs the exact wording: `invd events transcript-text <event_id> --split sections`, `invd events transcript AAPL 2026Q3` (turns with `start_ms`), or `invd search transcripts "<keywords>" --event <event_id>` (MCP `search_transcripts`; `--mode literal` for an exact figure, term or quote)
+   - when the call has documents (`has_documents`): `invd investor-documents AAPL --event <event_id>` (CFO commentary, shareholder letter, data sheets); for context beyond the call (annual report, investor-day deck) `invd search investor-documents "<keywords>" --company AAPL`; a `meta.coverage` of `pending` / `partial` means no hits is not proof the topic is absent
 3. **Summarise**:
-   - **Results vs guidance** — reported figures from the press release against the guidance given on the prior call (`invd earnings guidance-history -i <TICKER> --metric <metric>` for a metric's series).
+   - **Results vs guidance** — reported figures from the press release against the guidance given on the prior call (`invd guidance AAPL --metric revenue` for a metric's series across calls).
    - **Guidance changes** — each item raised, lowered, maintained, introduced or withdrawn (`direction`), with the period and basis (GAAP / non-GAAP).
    - **Analyst focus** — the recurring Q&A themes, who asked (firm), and where management deflected.
-   - **Tone change** — the diff's tone shift, hedging / uncertainty changes and new or dropped topics.
-   - **Price moves during the call** (only when fetched) — the largest minutes (`top_minutes`) and what was being said then. Word it as temporal coincidence, never as the cause of the move; pre-market bars are sparse.
-4. **Cite evidence** — every quote or claim carries its `[m:ss]` timestamp (from `start_ms`) and the speaker; a passage from a company document carries its document title, year and page and is described as company-published, not as a verified fact; separate what was said from your interpretation.
+   - **Tone change** — the comparison's tone shift, hedging / uncertainty changes and new or dropped topics.
+   - **Price moves during the call** (only when fetched) — the largest minutes and what was being said then. Word it as temporal coincidence, never as the cause of the move; pre-market bars are sparse.
+4. **Cite evidence** — every quote or claim carries its `[m:ss]` timestamp (from `start_ms`) and the speaker; a passage from a company document carries its title, year and page and is described as company-published, not as a verified fact; separate what was said from your interpretation.
 5. Flag what is missing (no press release, no guidance extracted, prior call not covered) instead of inferring it.

package/claude-plugin/commands/analyze-filing.md

@@ -5,11 +5,12 @@ argument-hint: <ticker> [form type or research question]
 
 # Analyze SEC Filing
 
-Analyze the filing requested in `$ARGUMENTS` using Invinite Data.
+Analyze the filing requested in `$ARGUMENTS` using Invinite Data (MCP `list_filings`, `read_filing`, `search_filings`, or the `invd` commands below with `--json`; the MCP server also offers the `summarise_10k_risk_factors` prompt).
 
-1. Resolve the company and identify the relevant filing and accession number.
-2. Discover valid filing section IDs before requesting sections.
-3. Retrieve only the sections needed for the question, normally risk factors, MD&A, business, and financial statements.
-4. Separate direct filing evidence from your interpretation.
-5. Report the form type, filing date, accession number, and section for every material finding.
-6. Flag missing sections or unavailable periods instead of inferring their contents.
+1. Resolve the company (`invd companies list -q "<name>"`, or `invd filers list -q "<name>"` for an unlisted filer) and find the filing and its accession: `invd filings AAPL --form 10-K --limit 1 --json`.
+2. Open the filing's documents for the `version_id` of the primary document: `invd filings get 0000320193-26-000026 --expand documents --json`.
+3. Discover valid section ids (`invd catalog sections --form 10-K --json`), then list the version's sections: `invd documents sections <version_id> --json`.
+4. Read only the sections the question needs (normally risk factors, MD&A, business, financial statements): `invd documents get <version_id> --blocks <blocks> --json`. For a topic across filings use `invd search filings "<keywords>" --company AAPL --form 10-K --json` (100 credits a page).
+5. Separate direct filing evidence from your interpretation.
+6. Report the form type, filing date, accession number, section and `version_id` + `block_id` (with the printed page label when present) for every material finding.
+7. Flag missing sections, unavailable periods or a `pending` / `partial` coverage note instead of inferring their contents.

package/claude-plugin/commands/compare-companies.md

@@ -5,11 +5,11 @@ argument-hint: <tickers or company names> [focus]
 
 # Compare Companies
 
-Compare the companies in `$ARGUMENTS` using Invinite Data.
+Compare the companies in `$ARGUMENTS` using Invinite Data (MCP `search_companies`, `get_company`, `get_financials`, `get_metrics`, or the `invd` commands below with `--json`; the MCP server also offers the `compare_companies` prompt).
 
-1. Resolve ambiguous company names with `company_search` or the equivalent `invd` command.
-2. Fetch available metric definitions before requesting financial metrics.
-3. Fetch company details, the latest annual standardized snapshot, profitability and valuation ratios, and five-year CAGR where available.
+1. Resolve ambiguous company names with `search_companies` or `invd companies list -q "<name>" --json`.
+2. Fetch the metric definitions before reading financial metrics: `invd catalog metrics --json`.
+3. Fetch, for all companies in one call each: company details (`invd companies get AAPL --json`), the latest annual standardized snapshot (`invd financials AAPL MSFT --fiscal-year 2025 --json`), profitability and valuation ratios (`invd metrics ratios AAPL MSFT -p annual --category profitability,valuation --json`) and five-year CAGR (`invd metrics cagr AAPL MSFT -p annual --horizon 5 --json`) where available.
 4. Run independent reads in parallel when the active Claude surface supports it.
 5. Present a compact comparison table followed by the most material strengths, weaknesses, and data limitations.
-6. Cite the reporting periods used; do not mix annual and quarterly values without labeling them.
+6. Cite the reporting periods used; do not mix annual and quarterly values without labeling them, and note when companies' fiscal years end in different months.

package/claude-plugin/commands/financial-research.md

@@ -12,13 +12,13 @@ You are a financial research orchestrator. The user has asked you to research or
 
 Break the user's request into independent data retrieval tasks. Think about what data sources you need:
 
-- **Company fundamentals**: company details, financial snapshots
-- **Metrics & ratios**: profitability, valuation, liquidity, solvency ratios, CAGR, growth rates
-- **Statements**: income statements, balance sheets, cash flows (for trend analysis)
-- **Ownership**: institutional holders, ownership transactions, insider trades
-- **Filings**: SEC filing sections (risk factors, MD&A, business descriptions)
-- **Earnings calls**: call calendar, transcripts, management guidance and KPIs, Q&A with analysts, press releases, the diff vs the prior call
-- **Context**: dividends, stock splits, fiscal periods, segments
+- **Company fundamentals**: company profile, financial statements (several companies in one call for a snapshot)
+- **Metrics & ratios**: profitability, valuation, liquidity, leverage and efficiency ratios, CAGR, growth rates (read the metric catalog first)
+- **Statements**: income statements, balance sheets, cash flows, standardized or as-reported, point in time (for trend analysis)
+- **Ownership**: 13F holders, quarter-over-quarter position changes, insider trades
+- **Filings**: SEC filing sections (risk factors, MD&A, business descriptions), full-text filing search
+- **Earnings calls**: call calendar, transcripts, management guidance and KPIs, Q&A with analysts, press releases, the comparison with the prior call
+- **Context**: dividends, stock splits, fiscal periods, segments, company news and announcements
 
 Each independent data need becomes a separate subagent task.
 
@@ -28,7 +28,7 @@ Launch all data retrieval tasks at the same time using the `invinite-data` agent
 
 **Example**: if the user asks "Compare Apple and Microsoft's financial health", spawn subagents in parallel like:
 
-1. `invinite-data`: "Fetch the latest annual financial snapshot for AAPL and MSFT"
+1. `invinite-data`: "Fetch the latest annual standardized financial statements for AAPL and MSFT in one call"
 2. `invinite-data`: "Fetch profitability and liquidity ratios for AAPL, annual period"
 3. `invinite-data`: "Fetch profitability and liquidity ratios for MSFT, annual period"
 4. `invinite-data`: "Fetch 5-year CAGR metrics for AAPL and MSFT"
@@ -37,7 +37,7 @@ Launch all data retrieval tasks at the same time using the `invinite-data` agent
 - Always spawn as many subagents in parallel as possible — do not fetch sequentially
 - Give each subagent a specific, focused task — one clear data request per agent
 - If the user mentions companies by name (not ticker), include "resolve the ticker first" in the subagent prompt
-- For comparative analysis, consider fetching data for all companies in a single snapshot call rather than one per company
+- For comparative analysis, fetch all companies in one call (`invd financials AAPL MSFT --fiscal-year 2025`, `invd metrics ratios AAPL MSFT`) rather than one per company
 
 ## Step 3: Analyze and synthesize
 

package/claude-plugin/commands/ownership-review.md

@@ -5,10 +5,10 @@ argument-hint: <ticker> [period or focus]
 
 # Review Ownership
 
-Review ownership activity for `$ARGUMENTS` using Invinite Data.
+Review ownership activity for `$ARGUMENTS` using Invinite Data (MCP `get_holdings`, `get_insider_trades`, or the `invd` commands below with `--json`).
 
-1. Resolve the company identifier.
-2. Fetch institutional holdings, institutional transactions, and insider trades for the requested period.
-3. Identify the largest holders, notable new or exited positions, and meaningful insider acquisitions or dispositions.
-4. Distinguish position value from share count and filing date from transaction date.
-5. Present concise tables and call out reporting-lag limitations in institutional filings.
+1. Resolve the company identifier (`invd companies list -q "<name>" --json` when given a name).
+2. Fetch institutional holdings (`invd holdings AAPL --period-end 2026-06-30 --json`), quarter-over-quarter position changes (`invd holdings changes AAPL --json`) and insider trades (`invd insider-trades AAPL --filed-at-gte 2026-01-01 --json`) for the requested period.
+3. Identify the largest holders, notable new or exited positions (`--type new,sold_out`), and meaningful insider acquisitions or dispositions (`--side buy` / `--side sell`).
+4. Distinguish position value from share count and filing date from transaction or quarter-end date.
+5. Present concise tables and call out reporting-lag limitations in institutional filings (13F positions are as of the quarter end, filed up to 45 days later).