etfray 0.1.0

ETF research and portfolio analytics terminal

etfray

A terminal-based ETF research and portfolio analytics application built with Textual.

etfray converts SEC fund filings and IBKR portfolio data into holdings, exposure, concentration, margin, and risk workflows — all from your terminal.

Why etfray?

• No cloud accounts — No sign-ups, no API keys to manage, no third-party dashboards. Your data stays on your machine.
• No subscriptions — ETF holdings data comes directly from SEC EDGAR filings. Free, authoritative, and always available.
• Offline-capable — All data is cached locally in SQLite. After the first fetch, everything works without a network connection.
• Keyboard-first — Designed for speed. Command palette, tree navigation, and keybindings — no mouse required.

Features

• ETF Research — Search ETFs, view holdings, sector/geographic exposure, concentration, fees, risk metrics, and SEC documents via EDGAR
• Portfolio Analytics — Connect to IBKR TWS/Gateway for live positions, lookthrough exposure, concentration analysis, and margin/leverage monitoring
• Side-by-side Compare — Compare multiple ETFs across holdings, exposure, and fees in a single view
• Export — Save any view to CSV or JSON for further analysis
• Keyboard-first — Full TUI with command palette, tree navigation, and keybindings
• Local & private — All data cached locally in SQLite; no cloud accounts required

Key Capabilities

Capability	Details
ETF coverage	10,000+ ETFs via SEC EDGAR N-PORT filings
Data sources	EDGAR (official), alternative web scraper, IBKR TWS
Holdings analysis	Full position-level breakdown with weight, value, shares
Exposure	Sector and geographic exposure from underlying holdings
Concentration	Top-N analysis (top 10, 25, 50) with cumulative weight
Portfolio	Real-time positions, lookthrough exposure, margin & leverage
Storage	Local SQLite — no cloud, no external databases
Freshness	Configurable staleness thresholds (default: 30 days fresh, 90 days acceptable)

Usage Examples

Research an ETF

1. Launch etfray and navigate to Research → Search in the sidebar
2. Press ctrl+p to open the command palette, type a ticker (e.g., VTI)
3. Browse tabs: Holdings → Exposure → Concentration → Risk
4. Click the Export button to save the current view to CSV

Monitor your portfolio

1. Ensure IBKR TWS/Gateway is running with API enabled on port 7497
2. Navigate to Portfolio → Positions in the sidebar
3. etfray connects lazily — positions load automatically on first access
4. Switch to Lookthrough to see aggregated exposure across all your ETF holdings
5. Check Margin for leverage ratio and margin cushion warnings

Architecture

graph LR
    A[SEC EDGAR API] --> C[Data Services]
    B[Web Scraper] --> C
    D[IBKR TWS API] --> C
    C --> E[(SQLite Cache)]
    E --> F[Domain Analytics]
    F --> G[Textual TUI]

Design principles:

• Local-first — All data cached in SQLite. Works offline after initial fetch.
• Source provenance — Every data point tracks its origin and fetch date so you know how fresh it is.
• Lazy connection — IBKR connects only when portfolio views are accessed, not at startup.
• Separation of concerns — data/ handles I/O, domain/ handles computation, ui/ handles presentation.

Configuration

All settings are managed via Workspace → Settings in the sidebar and stored in ~/.etfray/data.db.

Setting	Default	Description
ibkr_port	7497	IBKR TWS/Gateway API port
edgar_identity	(empty)	Your email — required by SEC fair use policy
data_source	auto	Holdings source: auto, edgar, or web
freshness_days_fresh	30	Days before cached data is considered stale
margin_warning_cushion	0.15	Margin cushion threshold for warnings

See the full configuration reference for all options.

Installation

pip install etfray

Requires Python 3.11+.

Quick Start

etfray

Use the sidebar tree to navigate between Research and Portfolio workspaces. Press ctrl+p to open the command palette.

IBKR Connection

To use portfolio analytics, you need IBKR TWS or IB Gateway running with API connections enabled (default port 7497).

Configure the connection in Workspace → Settings in the sidebar.

Documentation

Full documentation at etfray.readthedocs.io:

• Installation
• User Guide
• IBKR Setup
• Developer Guide

Development

git clone https://github.com/alwank/etfray.git
cd etfray
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs]"
pytest

License

MIT