Developer Tools

SEC EDGAR

pp-sec-edgar

Every SEC filing, every XBRL fact, every insider trade — synced into a local SQLite store you can pivot, search,...

Printed by @ChrisDrit (Chris Drit)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install sec-edgar

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-sec-edgar --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-sec-edgar skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-sec-edgar. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

Every SEC filing, every XBRL fact, every insider trade — synced into a local SQLite store you can pivot, search, and watch offline.

An agent-native CLI for the entire SEC EDGAR surface — data.sec.gov XBRL, efts.sec.gov full-text search, and the live Atom feed. The synced SQLite store enables joins no single SEC endpoint supports: insider-cluster detection across issuers, XBRL peer-group benchmarks by SIC, 13F holdings deltas across quarters, and live filing watches with multi-dimensional filters. All free — SEC provides no API key, just a mandatory User-Agent header.

Authentication

SEC EDGAR requires no API key. Every request must include a User-Agent header naming a human and contact email (e.g. 'Alex Researcher alex@example.com'). Set SEC_EDGAR_USER_AGENT in your environment; the CLI refuses to run without it. The SEC enforces a 10-req/sec rate cap per host; this CLI caps itself at 8 req/sec with jitter.

Quick Start

# Confirm the User-Agent is set and SEC hosts are reachable.
sec-edgar-pp-cli doctor

# Resolve a ticker to its CIK from the local company-ticker map.
sec-edgar-pp-cli companies lookup AAPL --json

# Apple's last five 10-Ks from the synced submissions store.
sec-edgar-pp-cli filings list --cik 0000320193 --form 10-K --limit 5 --json

# Apple's last four quarters of income-statement XBRL facts.
sec-edgar-pp-cli facts statement --cik 0000320193 --kind income --periods last4 --json

# Flag issuers with 3+ insiders selling in any 5-day window over the last 30 days.
sec-edgar-pp-cli insider-cluster --within 5d --min-insiders 3 --code S --since 30d --json

# Stream live filings matching multi-dim filters as NDJSON.
sec-edgar-pp-cli watch --form 8-K --item 2.05 --keyword 'going concern' --json

Unique Features

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

Local state that compounds

watchlist items — Across a saved watchlist of CIKs, surface 8-Ks filed in the window grouped by Item code (2.05 restructuring, 5.02 exec change, 4.02 non-reliance).

Equity analysts triage filings by Item code, not by company. Pick this when an agent needs cross-company 8-K filtering by Item.
```
sec-edgar-pp-cli watchlist items --since 30d --item 2.05,5.02,4.02 --cik 0000320193,0000789019,0001652044 --json
```
insider-cluster — Flag issuers where 3+ distinct insiders filed Form 4 with the same transaction code (open-market buy or sale) within a rolling N-day window.

Clustered insider selling is a textbook forensic signal. Pick this when an agent needs derived signals over raw Form 4 data.
```
sec-edgar-pp-cli insider-cluster --within 5d --min-insiders 3 --code S --since 90d --json
```
industry-bench — Take an XBRL concept for one reporting period, group by SIC code, and emit percentile statistics (p10/p50/p90) across every public-company filer in that SIC.

Quant researchers and equity analysts need peer-group benchmarks. Pick this when an agent should answer 'how does X compare to its industry peers'.
```
sec-edgar-pp-cli industry-bench --tag us-gaap:Revenues --period CY2024Q4 --sic 7372 --stat p50,p90 --json
```
cross-section — Pivot a single XBRL concept across an explicit company list and the last N reporting periods. Output as a wide pivot table (one row per company, one column per period).

Comp-set analysis is one of the highest-frequency analyst rituals. Pick this when an agent compares fundamentals across an explicit ticker list.
```
sec-edgar-pp-cli cross-section --tag us-gaap:Revenues --ticker AAPL,MSFT,GOOGL --periods last8 --json
```
holdings delta — Diff an institutional investor's 13F holdings across two consecutive quarters. Categorize each issuer as ADD / EXIT / INCREASE / DECREASE with share-count delta.

Tracking institutional money flow is a classic factor signal. Pick this when an agent compares a fund's positioning across quarters.
```
sec-edgar-pp-cli holdings delta --filer-cik 0001067983 --period 2024Q4 --vs 2024Q3 --json
```

Agent-native plumbing

watch — Stream the SEC Atom getcurrent feed with multi-dimensional filtering: form type, 8-K item, CIK watchlist, and keyword regex. Emits one NDJSON line per match.

Agents that monitor for specific filing events should subscribe to this stream rather than polling submissions per CIK.
```
sec-edgar-pp-cli watch --form 8-K --item 2.05 --cik 0000320193,0000789019 --keyword 'going concern' --one-shot --json
```

SEC-specific signals

restatements — Surface 8-K Item 4.02 (non-reliance on prior financials) plus all 10-K/A and 10-Q/A amendments filed in the window — the textbook accounting-irregularity signal.

Forensic accounting agents look for restatements as a leading indicator of trouble. Pick this when an agent needs accounting-quality signals.
```
sec-edgar-pp-cli restatements --since 90d --json
```
late-filers — Find issuers that filed an NT 10-K, NT 10-Q, or NT 20-F in the window — the SEC's 'I'm going to miss my reporting deadline' notification.

Late filings are leading indicators of operational or accounting trouble. Pick this when an agent needs to flag at-risk companies.
```
sec-edgar-pp-cli late-filers --since 90d --form 10-K --json
```

Usage

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

Commands

companies

Company directory (ticker → CIK → name)

sec-edgar-pp-cli companies tickers - Full ticker-to-CIK map for every public-equity issuer with a listed ticker (~10k entries)
sec-edgar-pp-cli companies tickers_exchange - Ticker-to-CIK map keyed by exchange (Nasdaq, NYSE, etc.)
sec-edgar-pp-cli companies tickers_mf - Mutual fund ticker-to-CIK map (one row per share class)

facts

XBRL financial facts (data.sec.gov)

sec-edgar-pp-cli facts company - Get all XBRL facts for a company across every reporting period
sec-edgar-pp-cli facts frame - Get one XBRL concept value reported by every public filer for one period (cross-company slice)
sec-edgar-pp-cli facts get - Get a single XBRL concept time series for one company (one tag across all of its filings)

submissions

Filer (company) filing history

sec-edgar-pp-cli submissions get - Get full submissions history for a filer by 10-digit zero-padded CIK

Output Formats

# Human-readable table (default in terminal, JSON when piped)
sec-edgar-pp-cli facts get --cik example-value --taxonomy example-value --tag example-value

# JSON for scripting and agents
sec-edgar-pp-cli facts get --cik example-value --taxonomy example-value --tag example-value --json

# Filter to specific fields
sec-edgar-pp-cli facts get --cik example-value --taxonomy example-value --tag example-value --json --select id,name,status

# Dry run — show the request without sending
sec-edgar-pp-cli facts get --cik example-value --taxonomy example-value --tag example-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
sec-edgar-pp-cli facts get --cik example-value --taxonomy example-value --tag example-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

sec-edgar-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/sec-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
`SEC_EDGAR_USER_AGENT`	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

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

API-specific

HTTP 403 from data.sec.gov — The User-Agent header is missing or generic. Set SEC_EDGAR_USER_AGENT='Your Name your@email.com' and retry.
HTTP 429 (rate-limited) — Reduce concurrency. The CLI caps at 8 req/sec by default; --concurrency 4 halves it. Sync commands resume from cursor.
CIK not found — CIKs are 10 digits with leading zeros. Use 'companies lookup ' to resolve; the CLI also accepts un-padded CIKs and pads them.
Empty 'facts company' output for a known filer — Not all filers report XBRL (e.g. older filings, foreign private issuers using 20-F). 'filings list' shows what they did file.

Sources & Inspiration

This CLI was built by studying these projects and resources:

edgartools — Python
sec-edgar-mcp — Python
secedgar — Python
sec-api-python — Python
sec-edgar-toolkit — TypeScript
bellingcat-edgar — Python
tumarkin-edgar — Go

Generated by CLI Printing Press