EDGAR CLI

An agent-native CLI for SEC EDGAR — six sanctioned endpoints, SQLite-cached filings with FTS5, and LODESTAR-shaped compound bundles (primary-sources, insider-summary) that no other EDGAR tool emits.

Built for a Claude Code agent doing conviction research on public-company filings. Compound commands collapse a ticker's full primary-source pull into one structured response; insider-summary distinguishes discretionary code-S sales from RSU-tax code-F noise and flags senior officers separately. Local SQLite cache with tiered TTLs makes re-reads near-free; FTS5 over cached bodies eliminates re-hitting EDGAR for the same query.

Created by @magoo242 (magoo242).

Authentication

No API key — SEC EDGAR is publicly accessible. Identity is the User-Agent: set COMPANY_PP_CONTACT_EMAIL once and every request goes out as lodestar-edgar-pp-cli <email>. The CLI refuses to run if the env var is unset, with a clear error pointing at setup. Rate-limited to ≤2 req/sec sustained (well under SEC's 10 req/sec ceiling) with adaptive backoff on 429.

Quick Start

# SEC fair-access requires a real contact email in the User-Agent. Set once.
export COMPANY_PP_CONTACT_EMAIL=user@example.com

# Verifies UA env var, runs a reachability probe against data.sec.gov, opens the SQLite store, confirms FTS5.
edgar-pp-cli doctor

# LODESTAR primary-source bundle: latest 10-K, four 10-Qs, 90-day 8-Ks, 12-month Form 4s with senior-officer flag, latest DEF 14A — all in one structured response.
edgar-pp-cli primary-sources AAPL --json

# Form 4 aggregator with code-S (discretionary) vs code-F (RSU tax) separated and senior officers flagged.
edgar-pp-cli insider-summary AAPL --senior-only --since 12mo --json

# Recheck delta — only filings filed after the supplied timestamp, using the local cursor.
edgar-pp-cli since AAPL --as-of 2026-05-08 --json

Unique Features

These capabilities aren't available in any other tool for this API.

Local state that compounds

• since — Return only the filings filed since a given timestamp, using a per-CIK local cursor — the entire LODESTAR /$recheck loop in one call.

  For quarterly thesis rechecks, reach for this before fetching the full submissions index — it eliminates re-paying token cost on filings already seen.

  edgar-pp-cli since AAPL --as-of 2026-05-08 --json
  

• fts — Full-text search over locally-cached filing bodies via FTS5 — ticker- and form-scoped — with snippet windows and byte offsets for precise re-read.

  Reach for fts during deep-dives where you re-query the same filing body multiple times; reach for the absorbed efts command for the first lookup or for cross-issuer queries.

  edgar-pp-cli fts "going concern" --ticker AAPL --form 10-Q --json
  

Service-specific content patterns

• eightk-items — Enumerate 8-Ks with parsed Item numbers and a --material-only flag that excludes exhibits-only (Item 9.01 alone) refilings.

  Use this instead of pulling 8-K bodies when you need 'has anything material happened?' — answers in one call without reading filing text.

  edgar-pp-cli eightk-items AAPL --since 2026-05-08 --material-only --json
  

• ownership-crosses — Enumerate 13D and 13G filings against an issuer (when someone else crosses 5% of the ticker), with filer name, percent owned, and filed-at.

  Use in LODESTAR Gate 3 asymmetric-structure checks to spot activist or institutional concentration without scrolling submissions.

  edgar-pp-cli ownership-crosses AAPL --json
  

• governance-flags — Compose three independent service-specific signals into one call: 8-K Item 4.01 auditor changes, Item 4.02 non-reliance restatements, and NT-10-K late-filing notices (Form 12b-25).

  Use as an early disqualifier check — if any flag fires, surface to LODESTAR before spending tokens on the full thesis.

  edgar-pp-cli governance-flags AAPL --since 2y --json
  

Cross-entity joins

• insider-followthrough — For every senior-officer code-S sale of ≥$1M, scan the next 90 days of 8-Ks for material items and emit (sale, subsequent material 8-K, days-between) pairs.

  Reach for this in LODESTAR Gate 2 execution-validation when an insider sale precedes material disclosures — surface management exits before bad news.

  edgar-pp-cli insider-followthrough AAPL --json
  

  Form 4 ingest cap. insider-summary, insider-followthrough, and primary-sources ingest Form 4 filings through a shared --max-form4 N cap (default 200) that bounds DB/API pressure on high-volume filers (large biotechs during offerings, late-stage IPOs). When the cap clips older filings, the JSON output surfaces form4_truncated: true and form4_total_in_window: <N> under form4_skipped, and a stderr WARN fires so the truncation is never silent. Pass --max-form4 0 to disable the cap entirely; pass a larger value to widen it.

• xbrl-pivot — Multi-ticker XBRL pivot that resolves concept aliases (Revenues ↔ RevenueFromContractWithCustomerExcludingAssessedTax ↔ SalesRevenueNet) into a flat ticker×quarter×concept table.

  For cross-sectional quality screens — pivot before parsing 50 companyfacts JSON blobs by hand.

  edgar-pp-cli xbrl-pivot --tickers AAPL,MSFT,GOOGL --concepts Revenues,NetIncomeLoss --quarters 8 --csv
  

Token-efficient extraction

• sections — Extract requested Items from a 10-K or 10-Q with byte-offset boundaries; emits ONLY the requested items in compact JSON instead of the full 100KB-10MB HTML body.

  Use this instead of fetching the raw 10-K body — saves an order of magnitude in tokens when you only need Risk Factors and MD&A.

  edgar-pp-cli sections AAPL --form 10-K --items 1A,7,7A --json
  

Usage

Run edgar-pp-cli --help for the full command reference and flag list.

Commands

companies

Company identifiers (ticker → CIK) and per-issuer submissions index

• edgar-pp-cli companies lookup - Resolve ticker → CIK (and company name + SIC) from SEC's nightly index. Cache 24h in local SQLite.
• edgar-pp-cli companies submissions - Structured submissions index for a company (filing history with accession numbers, form types, filed-at).

companyfacts

XBRL company facts (financial concepts: revenue, net income, assets, cash flow, etc.) for a CIK

• edgar-pp-cli companyfacts get - All XBRL company facts for a CIK. Optionally filter to a single concept client-side.

efts

EDGAR full-text search across all filings (efts.sec.gov). For offline FTS5 over cached filing bodies, use the offline fts command instead.

• edgar-pp-cli efts query - Online full-text search across EDGAR filings. For offline FTS5 over cached bodies, use edgar-pp-cli fts.

filings

Per-form-type filing retrieval and individual filing document fetch

• edgar-pp-cli filings browse - EDGAR filing index for a CIK + form type. Returns HTML/Atom; the generator wraps it but parsing happens in the compound commands.
• edgar-pp-cli filings get - Fetch raw filing index page or document for a specific accession. Accession must be the no-dashes form (e.g., 000032019322000049).

Output Formats

# Human-readable table (default in terminal, JSON when piped)
edgar-pp-cli companyfacts mock-value

# JSON for scripting and agents
edgar-pp-cli companyfacts mock-value --json

# Filter to specific fields
edgar-pp-cli companyfacts mock-value --json --select id,name,status

# Dry run — show the request without sending
edgar-pp-cli companyfacts mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
edgar-pp-cli companyfacts mock-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 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, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

edgar-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/edgar-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
COMPANY_PP_CONTACT_EMAIL	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

• Run edgar-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $COMPANY_PP_CONTACT_EMAIL Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• Exit code 4 with 'COMPANY_PP_CONTACT_EMAIL not set' — export COMPANY_PP_CONTACT_EMAIL=user@example.com — SEC fair-access requires identification in the User-Agent.
• Exit code 3 with 'rate limited (HTTP 429)' — The 2 req/sec limiter is conservative but adaptive backoff is in play; if persistent, your IP may be in a 10-minute SEC penalty box — wait, then retry.
• Exit code 7 with 'cache miss and --offline' — Drop --offline or run edgar-pp-cli sync first to warm the local SQLite store.
• Wrong ticker → CIK after corporate action — edgar-pp-cli sync-tickers — refreshes company_tickers.json (24h TTL).
• Form 4 amounts look wrong — Use --senior-only and verify the column is is_discretionary; code F (RSU tax withholding) is non-directional and should be excluded from net sells.

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• edgartools — Python (2100 stars)
• secedgar — Python (1400 stars)
• sec-edgar-mcp — Python (265 stars)
• sec-edgar-toolkit — Python
• jadchaar/sec-edgar-downloader — Python
• palafrank/edgar — Go

Generated by CLI Printing Press