RiskModels CLI

Overview

The RiskModels CLI provides direct access to equity risk model data from your terminal. Query factor metrics, hedge ratios, risk decompositions, and ticker metadata with SQL.

Two modes:

  • API Key (billed) -- Queries route through riskmodels.net with per-request billing ($0.003/query). Recommended for production and AI agents.
  • Service Role Key (direct) -- Queries go directly to Supabase. For development and internal use.

Why Two Modes?

Our risk data is commercialized through a metered API to keep your costs low and our data fresh. However, we provide a powerful CLI that simplifies everything. Your team can explore the schema, test queries in local "Direct Mode," and then flip a switch to "Billed Mode" for production—where every request is secured, audited, and costs less than a penny.

For Developers: Use Direct Mode for rapid iteration, debugging, and bulk data operations without API rate limits or costs.

For Production & AI Agents: Use Billed Mode for secured, metered access with built-in usage tracking and cost controls.

Installation

npm install -g riskmodels-cli

Or from source:

git clone <repo> && cd cli
npm install && npm run install:global

Requires Node.js 18+.

Authentication

Option 1: API Key (Recommended)

riskmodels config init
# Select "API Key (billed)"
# Enter your rm_agent_* key

Or set directly:

riskmodels config set apiKey rm_agent_live_your_key_here

Get an API key at riskmodels.net/settings or via the provisioning endpoint:

curl -X POST https://riskmodels.net/api/auth/provision \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-app", "contact_email": "you@example.com"}'

Option 2: Service Role Key (Development)

riskmodels config init
# Select "Service Role Key (direct Supabase)"
# Enter your Supabase URL and service role key

Commands

query

Execute SQL SELECT queries against risk model data.

# Basic query
riskmodels query "SELECT * FROM ticker_metadata LIMIT 5"

# With custom limit
riskmodels query "SELECT ticker, l3_residual_er FROM ticker_factor_metrics" --limit 10

# JSON output (for piping to other tools)
riskmodels --json query "SELECT ticker, company_name FROM ticker_metadata LIMIT 3"

Pricing: $0.003 per query (API key mode). Free in direct mode.

schema

Explore available tables and columns.

# List all tables
riskmodels schema

# Show columns for a specific table
riskmodels schema --table ticker_factor_metrics
riskmodels schema --table ticker_metadata

config

Manage CLI configuration.

riskmodels config init          # Interactive setup
riskmodels config list          # Show current config
riskmodels config set <key> <value>  # Set a config value

balance

Check your account balance (API key mode only).

riskmodels balance

manifest

Generate AI tool manifests for integration with AI platforms.

riskmodels manifest                    # OpenAI format (default)
riskmodels manifest --format anthropic # Anthropic format
riskmodels manifest --format zed       # Zed editor format

Available Tables

| Table | Description | Update Frequency | |-------|-------------|-----------------| | ticker_factor_metrics | Latest risk metrics per ticker (HR, ER, RR, volatility) | Daily | | ticker_factor_metrics_free | Free-tier risk metrics | Daily | | ticker_metadata | Company info (name, sector, market cap) | Daily | | erm3_ticker_returns | Daily returns with factor decompositions | Daily | | erm3_l3_decomposition | Monthly factor decomposition history | Monthly | | etf_metadata | ETF information | Daily | | classification_mappings | Sector/industry classification mappings | Static |

Pricing

| Action | Cost | |--------|------| | SQL Query | $0.003 per request | | Schema exploration | Free | | Config management | Free | | Balance check | Free | | Manifest generation | Free |

Minimum top-up: $10. Top up via Stripe at /api/billing/top-up.

Agentic Usage

The CLI is designed for both human users and AI agents.

JSON Mode

All commands support --json for machine-readable output:

riskmodels --json query "SELECT ticker, l3_residual_er FROM ticker_factor_metrics LIMIT 3"

HTTP API (for agents without CLI)

Agents can call the endpoint directly:

curl -X POST https://riskmodels.net/api/cli/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rm_agent_live_your_key" \
  -d '{"sql": "SELECT ticker, l3_residual_er FROM ticker_factor_metrics LIMIT 5"}'

Response includes billing headers:

  • X-API-Cost-USD -- Cost of this request
  • X-Request-ID -- Request trace ID
  • X-Response-Latency-Ms -- Server latency

Tool Manifests

Generate tool definitions for AI platforms:

# For OpenAI function calling
riskmodels manifest --format openai > tools.json

# For Anthropic tool use
riskmodels manifest --format anthropic > tools.json

Insufficient Balance

When balance is too low, the API returns HTTP 402 with actionable details:

{
  "error": "Payment Required",
  "error_code": "INSUFFICIENT_BALANCE",
  "current_balance_usd": 0.001,
  "required_amount_usd": 0.003,
  "top_up_url": "/api/billing/top-up",
  "_agent": {
    "action": "top_up",
    "min_top_up_usd": 10,
    "retry_after_seconds": 60
  }
}

Example Queries

Screen for high residual risk stocks

riskmodels query "SELECT ticker, l3_residual_er, volatility FROM ticker_factor_metrics WHERE l3_residual_er > 0.5 ORDER BY l3_residual_er DESC LIMIT 20"

Get hedge ratios for a portfolio

riskmodels query "SELECT ticker, l3_market_hr, l3_sector_hr, l3_subsector_hr FROM ticker_factor_metrics WHERE ticker IN ('AAPL','NVDA','MSFT','GOOGL','AMZN')"

Company metadata lookup

riskmodels query "SELECT ticker, company_name, gics_sector_name, market_cap FROM ticker_metadata WHERE ticker = 'NVDA'"

Time series risk attribution

riskmodels query "SELECT date, l3_residual_er, l3_market_er, l3_sector_er FROM erm3_l3_decomposition WHERE ticker = 'AAPL' ORDER BY date DESC LIMIT 12"

Support

Last Updated: February 26, 2026 CLI Version: 1.0.0