BlackHart CLI

Query BRI scores from the terminal. Built for CI pipelines, audit workflows, and quick lookups. Zero runtime dependencies, single static binary.

download

Install

Install globally from npm. Requires Node.js 18+.

Terminal

npm install -g @blackhart/cli

Or run ad-hoc with npx @blackhart/cli <command>.

Commands

blackhart bri <slug>

Print the current BRI, Forge Scale, and dimension breakdown for a protocol.

Example output

$ blackhart bri aave-v3

  Aave V3
  ────────────────────────────────────────
  BRI            895       MITHRIL  (6/7)
  Updated        2026-05-22T14:00:00Z
  Confidence     71%
  Delta (7d)     +2

  D1  Access Control          92
  D2  Economic Soundness      88
  D3  Oracle Integrity        95
  D4  Compositional Risk      90
  D5  Governance              91
  D6  Battle-Tested Maturity  96
  D7  Adversarial Resilience  74
  D8  Supply Chain            87
  D9  Liquidity               85
  D10 Cross-Chain             82
  D11 OpSec                   89
  D12 Cascade Exposure        93

blackhart hacks

List the most recent confirmed DeFi exploits with severity, loss, and forensic links.

Example output

$ blackhart hacks

  Recent DeFi Hacks (last 30 days)
  ──────────────────────────────────────────────────────────────
  2026-05-20  squid-router      CRITICAL   $11.2M  module exploit
  2026-05-18  loopfi            HIGH        $2.4M  rebase race
  2026-05-14  abracadabra-v3    CRITICAL    $8.9M  oracle manipulation
  2026-05-09  velocore          HIGH        $6.8M  flash loan + reentrancy
  2026-05-03  yield-protocol    MEDIUM      $1.1M  governance attack

  See full timeline: https://blackhart.io/hacks

blackhart hack <slug>

Print the full forensic write-up, exploited contracts, and post-hoc BRI dimension changes for a specific incident.

Example output

$ blackhart hack squid-router

  HACK-SQUID-2026-001                                  CRITICAL
  ──────────────────────────────────────────────────────────────
  Protocol       Squid Router
  Date           2026-05-20T08:14Z
  Loss           $11.2M
  Attack Class   module-substitution + delegatecall

  Summary
    Attacker swapped a permitless WhitelistedCallsManager
    module pointer, then drained pooled approvals via
    delegatecall.

  BRI Impact
    D1  Access Control          -18  (84 -> 66)
    D4  Compositional Risk      -12  (82 -> 70)
    D11 OpSec                    -8  (90 -> 82)

  Full report: https://blackhart.io/hacks/squid-router

blackhart watch <slug> [--interval=300]

Poll the BRI for a protocol on an interval (seconds) and print any score changes as they happen. Defaults to 5 minutes.

Example output

$ blackhart watch lido --interval=300

  Watching lido (every 300s). Press Ctrl-C to stop.

  [2026-05-22T14:00:00Z]  BRI 887  DAMASCUS  stale=false
  [2026-05-22T14:05:00Z]  BRI 887  DAMASCUS  (no change)
  [2026-05-22T14:10:00Z]  BRI 884  DAMASCUS  delta=-3
  [2026-05-22T14:15:00Z]  BRI 884  DAMASCUS  (no change)

blackhart check <slug> --min-bri <N>

CI gate. Exits 0 if BRI >= threshold, exits 1 if below. Use as a build step.

Example output

$ blackhart check aave-v3 --min-bri 700

  Aave V3   BRI 895   MITHRIL   PASS  (threshold 700)
  $ echo $?
  0

$ blackhart check yield-protocol --min-bri 700

  Yield Protocol   BRI 612   FORGED   FAIL  (threshold 700)
  $ echo $?
  1

sync_alt

CI / GitHub Actions

Use blackhart check as a build gate. The step fails the workflow if any dependency drops below the threshold you set.

.github/workflows/bri.yml

name: BRI Gate

on:
  pull_request:
    branches: [main]

jobs:
  bri-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install BlackHart CLI
        run: npm install -g @blackhart/cli

      - name: Gate dependencies on BRI
        env:
          BLACKHART_API_KEY: ${{ secrets.BLACKHART_API_KEY }}
        run: |
          blackhart check aave-v3   --min-bri 700
          blackhart check uniswap-v4 --min-bri 750
          blackhart check lido      --min-bri 650

Environment Variables

Variable	Default	Description
`BLACKHART_API_URL`	`https://oracle.blackhart.io/api/v1`	Override the API base URL. Useful for staging or self-hosted mirrors.
`BLACKHART_API_KEY`	`(none)`	Optional API key. Without one you get the free tier (1,000 req/day). With one you get your plan's quota.

Open source

MIT licensed. Issues, PRs, and forks welcome.

codeView source

← API Plans Foundry plugin