Skip to content

api.md

Latest commit

 

History

History
152 lines (120 loc) · 7.91 KB

api.md

File metadata and controls

152 lines (120 loc) · 7.91 KB
Raw
title Finance Guru CLI reference
description Checked-in command entry points for the stable analysis engine
category reference

Finance Guru CLI reference

This is the checked-in command inventory, not a promise that every command is configured for every fork. Use --help before relying on a command's arguments or provider requirements. Commands that query markets or a personal integration may require network access or private credentials.

Command pattern

Run standalone scripts from the repository root with uv:

uv run python path/to/script.py --help

The refresh entry point is a Python module, not a standalone script:

uv run python -m src.integrations.refresh_all --help

Analysis commands

Command Purpose
src/analysis/correlation_cli.py Correlation and diversification analysis.
src/analysis/factors_cli.py Factor analysis.
src/analysis/hedge_comparison_cli.py Compare hedge approaches.
src/analysis/hedge_sizer_cli.py Calculate hedge sizing.
src/analysis/itc_risk_cli.py Query ITC risk-model data.
src/analysis/margin_metrics_cli.py Calculate margin metrics from configured local data. Prints JSON and has no --output flag. --source snaptrade adds equity_synced_at and raises StaleAccountEquityError when the equity sync time is missing, in the future, or older than 12 hours. The default DB source raises StaleEquitySnapshotError when the sync stored NULL margin debt, and adds ledger_synced_at, the sync time of the balances row it read. as_of_date is the run date, not the data date.
src/analysis/options_chain_cli.py Inspect options-chain data.
src/analysis/options_cli.py Run options calculations.
src/analysis/risk_metrics_cli.py Calculate risk and benchmark metrics.
src/analysis/rolling_tracker_cli.py Track a rolling analysis series.
src/analysis/total_return_cli.py Calculate total return.

Risk metrics use null for unavailable Sharpe, Sortino, and Calmar ratios. ratio_unavailable_reasons gives a typed reason for each null ratio, such as zero_volatility or no_drawdown. Finite ratios keep their numeric format. Text output and the terminal dashboard show unavailable ratios with their reasons.

Margin metrics require finite monthly dividend income and a finite FG_MARGIN_JUMP_ALERT_THRESHOLD. The calculator and CLI reject NaN and infinity before returning metrics. The CLI exits unsuccessfully and prints no metrics JSON. Zero and finite negative income remain valid. Omitted income remains optional.

Margin coverage uses --monthly-dividend-income, then FG_DIVIDEND_MONTHLY_INCOME, then the ledger's three closed calendar months. The ledger path uses only the configured taxable_margin account and USD DIVIDEND rows. The current partial month and other account roles are excluded. dividend_income names the source, window start, and exclusive window end. Missing history stays unavailable with a reason. The fallback opens the ledger read-only.

Total-return calculator models require finite price observations, dividend amounts, share counts, and return inputs. Missing prices, NaN, and infinities block calculation, including with --force. A zero terminal price remains valid and can produce a total loss. JSON output rejects nonfinite numbers, including portfolio CSV quantities, before printing or saving the report. The human report does not validate CSV quantities for finiteness. The CLI returns exit code 1 when all tickers fail or JSON formatting fails.

Implied volatility

options_cli.py --implied-vol --output json solves within the pricing model's annual volatility range of 0.01 through 3.0, inclusive. Time to expiry must be positive and at most 10 years. Interest and dividend rates range from 0.0 through 0.20. Inputs must be finite. Market premiums must be non-negative.

The solver brackets the premium between prices at the two volatility endpoints. A premium outside that range returns converged: false at the nearest endpoint, with its calculated price and absolute pricing error. The CLI writes this report, prints a non-convergence error to stderr, and exits with code 1. Valid solves keep exit code 0. A premium just outside the range does not converge, even when its price error is below the price tolerance.

Interior roots require a volatility bracket no wider than 1e-8 and a pricing error below $0.0001 per share, or an exact model-price match. iterations counts model price evaluations, including both endpoints, up to 100 evaluations. A zero premium converges only when the model also returns zero at its lower endpoint. Numerically flat prices can match more than one supported volatility. Zero volatility and zero time to expiry remain outside the pricing domain.

Strategy commands

Command Purpose
src/strategies/backtester_cli.py Backtest your strategy using supported implementations.
src/strategies/optimizer_cli.py Produce allocations for your portfolio using supported optimization methods.

Utility commands

Command Purpose
src/utils/data_validator_cli.py Check data quality.
uv run python -m src.utils.input_validation_cli Validate financial time-series inputs.
src/utils/market_data.py Retrieve market data.
src/utils/momentum_cli.py Calculate momentum indicators.
src/utils/moving_averages_cli.py Calculate moving averages and crossover signals.
src/utils/screener_cli.py Run the market screener.
src/utils/volatility_cli.py Calculate volatility indicators.
uv run python -m src.utils.yaml_generator_cli Generate supported YAML artifacts.

Interactive interface

Command Purpose
src/cli/fin_guru.py Start the Textual terminal interface.

uv run python -m src.cli.instance_init <root> --repo . is the supported setup command. The TypeScript onboarding wizard under scripts/onboarding/ predates it and is not part of the command contract.

Data refresh command

Command Purpose
uv run python -m src.integrations.refresh_all Refresh configured SnapTrade and SimpleFIN data into the local database.
uv run python -m src.integrations.snaptrade.cli Inspect linked SnapTrade accounts, positions, balances, or activities.
uv run python -m src.integrations.snaptrade.sync_db Refresh SnapTrade positions and balances into local SQLite. When SnapTrade equity fails that same check, it stores margin_debt as NULL and prints warning: account equity stale (last synced <ts>).
uv run python -m src.integrations.snaptrade.sync_transactions_db Refresh SnapTrade activities into local SQLite.
uv run python -m src.integrations.simplefin.sync_expenses_db Refresh SimpleFIN transactions into local SQLite.

Per-transaction category overrides

Your instance can hold a private category-overrides.yaml mapping transaction IDs to existing categories. refresh_all and sync_expenses_db apply these after merchant rules. The file stays outside Git. Re-sync keeps each override, while other transaction IDs keep their rule-based categories. Removing an override restores rule matching on the next sync for transactions still in the sync window. Duplicate keys, invalid categories, and IDs shared by multiple accounts block the sync.

synthetic-transaction-id: Groceries

Output and safety

Financial-analysis output is for educational purposes only. It is not investment advice. It may be wrong or incomplete, and loss of principal is possible. Review input data and results independently and consult appropriately licensed financial, tax, and legal professionals before acting.

Never put account numbers, balances, positions, access tokens, or database files in command arguments, checked-in examples, or Git commits. See Privacy and setup.