edgar-cli

Agent-friendly SEC EDGAR CLI for filings and company facts.

Features

• npx-friendly native Go runtime (no Node runtime after launch, no Python runtime)
• JSON envelope output by default for stable automation
• Strict SEC identity enforcement (--user-agent or EDGAR_USER_AGENT)
• Core commands:
  • resolve
  • search companies
  • company search
  • filings list
  • filings get
  • facts get
  • research sync
  • research ask

Install / Run

npx edgar-cli --help

Local development:

go test ./...
node npm/scripts/build-native.cjs
./dist/edgar --help
npm --prefix npm test

SEC Identity Requirement

SEC endpoints require declared automated access identity.

Use either:

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

Or pass per command:

npx edgar-cli --user-agent "Your Name your.email@example.com" resolve AAPL

If identity is missing, commands fail with IDENTITY_REQUIRED.

Examples

# Resolve ticker -> canonical SEC identity mapping
npx edgar-cli --user-agent "Your Name your.email@example.com" resolve AAPL

# Search SEC company/entity names -> CIKs
npx edgar-cli --user-agent "Your Name your.email@example.com" search companies "Space Exploration Technologies"

# List recent 10-K filings
npx edgar-cli --user-agent "Your Name your.email@example.com" filings list --id AAPL --form 10-K --query-limit 5

# Get filing document URL by accession
npx edgar-cli --user-agent "Your Name your.email@example.com" filings get --id AAPL --accession 0000320193-26-000006 --format url

# Get filing converted to Markdown
npx edgar-cli --user-agent "Your Name your.email@example.com" filings get --id AAPL --accession 0000320193-26-000006 --format markdown

# Write raw extracted filing text directly to a file
npx edgar-cli --user-agent "Your Name your.email@example.com" filings get --id AAPL --accession 0000320193-26-000006 --format text --output /tmp/aapl-10q.txt

# Emit raw extracted filing text to stdout instead of a JSON envelope
npx edgar-cli --user-agent "Your Name your.email@example.com" filings get --id AAPL --accession 0000320193-26-000006 --format text --raw

# Get concept data (latest per unit)
npx edgar-cli --user-agent "Your Name your.email@example.com" facts get --id AAPL --taxonomy us-gaap --concept Revenues --latest

# Query explicit local docs (repeat --doc or pass --manifest)
npx edgar-cli research ask "board resignation details" --doc ./cache/nvda-8k.md --top-k 5

# Build a deterministic cached corpus for a ticker/profile
npx edgar-cli --user-agent "Your Name your.email@example.com" research sync --id NVDA --profile core

# Query by ticker against cached corpus (auto-syncs on cache miss)
npx edgar-cli --user-agent "Your Name your.email@example.com" research ask "what changed on the board?" --id NVDA --profile core

# Query latest filing(s) in one shot: discover -> fetch/cache -> search
npx edgar-cli --user-agent "Your Name your.email@example.com" research ask "gross margin drivers" --id AAPL --form 10-Q --latest 1

Research Profiles and Cache

research sync and research ask --id use deterministic filing profiles:

• core: latest 1x 10-K, latest 3x 10-Q, and recent 8-K (last 180 days, up to 12)
• events: recent 8-K (last 365 days, up to 24)
• financials: latest 2x 10-K and latest 6x 10-Q

By default, cached corpora are stored in:

• $EDGAR_CACHE_DIR (if set), else
• $XDG_CACHE_HOME/edgar-cli (if set), else
• ~/.cache/edgar-cli

Override per command with --cache-dir.

When using research ask --id, you can also scope discovery directly:

• --form <form> to filter filings by form type (e.g. 10-Q)
• --latest <n> to limit selection to the latest N filings after filters

Output Contract (default)

All JSON-mode commands emit:

{
  "ok": true,
  "command": "resolve",
  "provider": "sec",
  "data": {},
  "error": null,
  "meta": {
    "timestamp": "2026-02-11T00:00:00Z",
    "output_schema": "v1",
    "view": "summary"
  }
}

Compliance Notes

• This CLI targets SEC-hosted endpoints only in V0.
• Respect SEC fair-access guidance and use a valid identity in your user-agent.

References:

• SEC Developer
• SEC Webmaster FAQ: code support

Security

See SECURITY.md for vulnerability reporting guidance.

Development

go test ./...
npm --prefix npm test
node npm/scripts/build-native.cjs