edgar-cli

0.1.4 verified Sat May 09 auth: no javascript

edgar-cli v0.1.4 is an agent-friendly CLI for accessing SEC EDGAR filings and company facts, designed for Node.js (>=18) and usable via npx without requiring Python. It provides commands for resolving tickers, listing/getting filings, extracting XBRL facts, and performing research syncing/querying with deterministic caching profiles. The CLI enforces SEC identity requirements via --user-agent or EDGAR_USER_AGENT and outputs stable JSON envelopes for automation. It differentiates from other EDGAR tools by being npx-friendly, TypeScript-native, and offering research capabilities with configurable filing profiles.

Common errors

error IDENTITY_REQUIRED: SEC EDGAR requires a declared identity ↓

cause EDGAR_USER_AGENT not set and --user-agent not provided.

fix

Set EDGAR_USER_AGENT environment variable or pass --user-agent 'Your Name your.email@example.com'.

error Error: No such file or directory: .../edgar-cli/cache/... ↓

cause Cache directory does not exist and cannot be created (permissions or missing parent directories).

fix

Ensure the cache directory is writable, or set EDGAR_CACHE_DIR to a writable path; create the directory manually if needed.

Warnings

gotcha SEC identity is required for all commands; missing EDGAR_USER_AGENT or --user-agent causes 'IDENTITY_REQUIRED' error. ↓

fix Set EDGAR_USER_AGENT environment variable or pass --user-agent to each command.

gotcha The --id parameter for resolve and filings commands expects a ticker symbol, not a CIK number or company name; incorrect input may yield empty results. ↓

fix Use the official ticker symbol (e.g., AAPL for Apple Inc.).

gotcha Filing accession numbers must include leading zeros and be in the format SEC uses (e.g., 0000320193-26-000006); omitting leading zeros may cause 'not found' errors. ↓

fix Copy the exact accession number from SEC EDGAR or use the filings list command to get valid accessions.

Install

npm install edgar-cli

yarn add edgar-cli

pnpm add edgar-cli

Imports

edgar-cli (binary)
wrong
```
npm install -g edgar-cli && edgar-cli --help (global install not required, use npx)
```
correct
```
npx edgar-cli --help
```
Recommended usage is via npx; global install works but npx avoids version conflicts.

EDGAR_USER_AGENT

wrong

Setting EDGAR_USER_AGENT in .env file (CLI reads only from environment variable, not .env)

correct

export EDGAR_USER_AGENT='Your Name your.email@example.com'

The CLI reads this environment variable at runtime; it is required for all SEC commands.

Quickstart

Demonstrates setting SEC identity and running resolve, filings list, and facts get commands.

export EDGAR_USER_AGENT='Example User user@example.com'
npx edgar-cli resolve AAPL
npx edgar-cli filings list --id AAPL --form 10-K --query-limit 2
npx edgar-cli facts get --id AAPL --taxonomy us-gaap --concept Revenues --latest