SEC API CLI

Query SEC filings, filing text, financial statements, XBRL facts, factor data, special situations, and traces from your terminal. The CLI writes JSON by default, so the same commands work in shells, scripts, and agent workflows.

Run bare secapi in an interactive terminal to open the REPL. Piped, CI, and flagged invocations remain one-shot commands. Set credentials in the environment before opening the REPL: its command runner does not accept --api-key-stdin or --bearer-token-stdin.

Install and verify

npm install -g @secapi/cli
secapi health

secapi health checks the API origin and does not require authentication. The package also installs omni-sec as a compatibility alias; use secapi in new scripts.

Get a filing

Set an API key, then retrieve the latest annual filing for a company:

export SECAPI_API_KEY="secapi_live_..."
secapi filings latest --ticker AAPL --form 10-K

The CLI reads credentials from the environment. It does not accept API keys or bearer tokens as command-line arguments. For CI or an agent runner, provide a key through standard input with --api-key-stdin instead.

Common workflows

# Resolve a company by ticker, CIK, or name.
secapi entities resolve --ticker AAPL

# Search filing text by keyword.
secapi search fulltext --q "supply chain disruption" --form 10-K --limit 10

# Search filing text semantically or with hybrid retrieval.
secapi search semantic --q "revenue concentration risk" --mode hybrid --view agent

# Extract Item 1A from the latest matching filing.
secapi sections get --ticker AAPL --form 10-K --section item_1a --view agent

# Retrieve normalized annual financial statements.
secapi statements get --ticker AAPL --statement all --period annual --limit 1

# Retrieve a single XBRL fact across filings.
secapi facts get --ticker AAPL --tag Assets --form 10-K

# List and export source-cited special situations.
secapi situations list --types merger --limit 10
secapi situations export --situation-id sit_...

Use --request-summary when a script needs request metadata on stderr while preserving the response JSON on stdout:

secapi filings latest --ticker AAPL --form 10-K --request-summary

Discover commands

secapi --help
secapi filings latest --help
secapi help all
secapi examples --json=false
secapi agent-context --output secapi-cli-context.json

secapi agent-context is local-only and emits a machine-readable inventory of commands, authentication requirements, mutation posture, output shapes, and examples. secapi examples provides runnable starter workflows without making an API request.

Configuration

The CLI uses https://api.secapi.ai by default. Override it for one command or select a named local profile:

secapi health --base-url http://127.0.0.1:8787

export SECAPI_PROFILE=local
secapi config show

Profiles live in ~/.config/secapi/profiles.json by default. They may specify baseUrl, apiKeyEnv, and bearerTokenEnv; the file stores environment variable names, never credential values. Set SECAPI_CONFIG_FILE to use a different profile file.

{
  "profiles": {
    "local": {
      "baseUrl": "http://127.0.0.1:8787",
      "apiKeyEnv": "SECAPI_LOCAL_API_KEY"
    }
  }
}

secapi --profile local config show
secapi config profiles
secapi doctor

secapi doctor checks the selected origin, credential source, API health, available account context, and hosted MCP configuration without printing credential values.

Factors and portfolios

Use compact responses when passing results to an agent, notebook, or UI:

secapi factors catalog --category style --response-mode compact --include trust
secapi factors history --factor VALUE --response-mode compact
secapi factors valuations --keys VALUE,QUALITY,MOMENTUM --side all --response-mode compact

Portfolio workflows take holdings from a JSON file for repeatable requests:

[
  { "symbol": "AAPL", "weight": 0.4 },
  { "symbol": "MSFT", "weight": 0.35 },
  { "symbol": "NVDA", "weight": 0.25 }
]

secapi portfolio analyze --holdings-file holdings.json --response-mode compact --include trust
secapi portfolio attribution --holdings-file holdings.json --window 1y --frequency monthly --response-mode compact
secapi portfolio hedge --holdings-file holdings.json --objective factor_neutral --response-mode compact

Traces

Filing-derived responses can include trace references. Retrieve one trace or several at once:

secapi traces get --trace-id trc_...
secapi traces list --ids trc_1,trc_2

Agent and shell setup

Configure a supported agent client for the hosted MCP server:

secapi init --client claude-code
secapi init --client cursor --print
secapi mcp install --client windsurf

--print previews the generated configuration without writing a file.

Generate shell completion scripts:

secapi completion zsh
secapi completion bash
secapi completion fish

Support

Create a redacted diagnostics bundle for support:

secapi support bundle --request-id req_...

The bundle includes local configuration, diagnostic results, and optional request details while redacting credential values.

Links

• API documentation
• Developer portal