Quickstart: CLI

Score a filing from the terminal in under a minute.

Audience: Terminal users and script writers. Before you start: Installation; SEC EDGAR Setup for --ticker.

Summary

Run disclosure-alpha score to print deterministic score JSON to stdout.

Local HTML

Goal: Score a filing you already have on disk — no network required.

# Committed fixture (from repo root)
disclosure-alpha score --html tests/fixtures/sample_10k.html --form 10-K

# Your own filing
disclosure-alpha score --html filing.html --form 10-K
disclosure-alpha score --html current.html --form 10-K --prior-html prior.html

Sample output

Scores block from a minimal synthetic 10-K (trimmed fixture):

      }
    },
    "language_deltas": {},
    "section_diffs_v2": {},
    "extraction_confs": {
      "item_1a_risk_factors": 0.35,
      "item_7_mdna": 0.35
    },
    "diff_confs": [
      0.2,
      0.2
    ],
    "extraction_warnings": [
      "short_section",
      "last_resort_extraction",
      "open_ended_boundary",
      "item1a_resliced",
      "extraction_suspect",
      "early_candidate"
    ],
    "required_sections_present": true,
    "has_prior": false

How to read it

  • overall_disclosure_risk_score — headline 0–100; see Understanding Scores

  • score_coverage_ratio — fraction of headline components computed

  • missing_components — often disclosure_change_score when no --prior-html is supplied

If something looks wrong

Low coverage or null change scores: FAQ and Troubleshooting.

By ticker + fiscal year

Goal: Fetch from EDGAR and score in one command. Requires SEC_USER_AGENT and network access.

export SEC_USER_AGENT="YourName your@email.com"
disclosure-alpha score --ticker AAPL --fiscal-year 2025 --form 10-K
disclosure-alpha score --ticker MSFT --fiscal-year 2025 --form 10-Q --quarter Q2

Sample output

Same JSON shape as local HTML. Filter with jq:

disclosure-alpha score --ticker AAPL --fiscal-year 2025 | jq '.scores.overall_disclosure_risk_score'

How to read it

  • Compare overall_disclosure_risk_score across tickers — not a buy/sell signal

  • Check versions if scores differ from a previous run

  • Inspect components for which language signals drove the headline

If something looks wrong

EDGAR errors and null components: FAQ and Troubleshooting.