ledgerbase-iris-cli

Read-only command-line client for the LedgerBase SEC fundamentals API. See AGENTS.md for module scope and invariants.

Install

npm install
npm run build
npm link   # exposes the `iris` command globally from this checkout

Requires Node 20+.

Quickstart

# 1. Get a key from the landing page's "Request access" form, then:
iris auth login <your-api-key>

# 2. Make a call
iris company AAPL
iris metrics latest AAPL

By default the CLI talks to http://localhost:8080. Point it elsewhere with LEDGERBASE_BASE_URL. LEDGERBASE_API_KEY overrides the stored key (handy for CI/scripting) — see ledgerbase-iris-cli/AGENTS.md for the full key-resolution order.

Commands

iris auth login <api-key>
iris auth logout
iris auth status

iris company <ticker>
iris search <query> [--limit N]
iris filings <ticker> [--form-type 10-K] [--limit N]
iris metrics latest <ticker> [--mode compact|wide|ai-context] [--fiscal-period FY]
iris metrics history <ticker> <metricKey> [--fiscal-period FY] [--limit N]
iris metrics explain <ticker> <metricKey> [--period-end YYYY-MM-DD]
iris metrics dictionary
iris data-quality <ticker>
iris fundamental-trends <ticker> [--fiscal-period FY] [--limit N] [--metrics revenue,net_income]
iris financial-health <ticker> [--fiscal-period FY]
iris ingest-health <ticker>

All read commands accept --format json|table (default: table; falls back to pretty JSON for responses with nested objects/arrays too deep for a plain table).

Safe example tickers: AAPL, MSFT, NVDA. AMZN and WMT are intentional partial-data examples (total_liabilities is MISSING by design). Do not default to TSLA, XOM, or JPM in examples or docs — see the Coverage & Demo Tickers topic in the live docs explorer (ledgerbase-landing's /docs) for the full matrix.

Exit Codes

0 success · 1 generic error · 2 auth error · 3 not found · 4 rate limited.

Development

npm run typecheck
npm run build
npm test     # builds, then runs tests/smoke.test.mjs against a local mock backend

tests/mock-server.mjs is a minimal Node HTTP server standing in for the real backend — it is not a replacement for testing against a live ledgerbase-backend instance, just a fast, dependency-free check that auth, the read commands, output formatting, and error mapping all wire together correctly.