investments: a Rust tool that reads your broker statements and does the arithmetic

The problem: knowing what you actually earned

The tool exists to answer a set of questions that broker statements do not answer well. The analysis command calculates the average rate of return from cash investments by comparing your portfolio performance against a bank deposit in USD and RUB with exactly the same investments and monthly capitalisation, and it takes taxes, commissions, dividends, tax deductions and optionally inflation into account while doing it. That benchmark is the interesting choice, because a deposit is what most retail investors were actually holding before, so comparing against it answers the question people really have, which is whether the extra risk was worth it, rather than how the portfolio did against an index. The rest of the feature list follows from the same logic. Backtesting runs your cash flows against configured benchmarks, portfolio rebalancing tells you which orders to submit to get back to your target allocation, and the sell simulation calculates revenue, profit, taxes and real profit percentage with taxes accounted for.

It reads statements rather than asking you to enter trades

The design decision that makes the tool different from a spreadsheet is that it is designed to work with your broker statements, so there is no need to enter all trades and transactions manually. The cost of that decision is a requirement, and it is stated precisely. You need all broker statements starting from account opening day, it may be one statement or many and it does not matter which, but the first statement must be with zero starting assets, and the periods of the statements must not overlap or have missing days in between. That is a real constraint on how you have to archive your paperwork, and a person who only kept recent statements will not be able to use the tool at all. The brokers whose statement formats are supported are Firstrade, Interactive Brokers, BCS, Sber and T-Bank, with a details page for each, and the tool is also aimed at investors holding non-exchange-traded unit investment funds.

The command set, and the two kinds of command

The commands are grouped into three kinds, and the grouping tells you what depends on what. The analysis commands, which are analyse, cash-flow, metrics, simulate-sell and tax-statement, read your broker statements and produce results, and they use the local database only for caching quotes. The sync command reads your broker statements and stores your current positions in the local database. The portfolio rebalancing commands, which are show, rebalance, cash, buy and sell, work only with the local database, so they depend on a sync having happened. The data itself lives in a SQLite database at ~/.investments/db.sqlite, and the configuration is a YAML file at ~/.investments/config.yaml, with an example file that contains typical configuration for each broker along with the tax exemptions that apply to your account. The documentation also asks you to obtain API tokens for the FCS and Finnhub quote providers.

Backtesting, and the VictoriaMetrics connection

The backtest command runs all your cash flows against the benchmarks you have configured, which lets you compare your portfolio performance with those benchmarks rather than with a single index. The part that makes it a long-running tool rather than a report is that the command also allows you to backfill backtesting results, the historical data, to VictoriaMetrics for further analysis. That is a sensible design for a personal investing tool, because the interesting questions are about the last three years and the answer changes every week as the market moves, so keeping the time series somewhere you can query is how you notice a change in behaviour rather than a change in the market. It also explains why the tool has a Prometheus metrics command, since the same argument applies to the analysis results themselves.

Metrics in Prometheus format, and the dashboard

The metrics command exports the analysis results in Prometheus format, to be collected by the Node exporter's Textfile Collector, and the project shows a Grafana dashboard that displays aggregated statistics and investment results for multiple portfolios opened in different brokers. The multi-portfolio angle is the one that matters, because the tool is explicitly aimed at people who hold accounts at several of the supported brokers, and the point of the dashboard is to see them together. The metrics command is one of the analysis commands, which means it reads the statements and uses the database only for quote caching, so the numbers it exports reflect your actual transactions rather than a manual re-entry.

Deposits, funds, and the tax statement

The bank deposit support is a small feature with a clear audience, since in Russia a meaningful part of a retail portfolio sits in deposits rather than in securities. You register your opened deposits in the configuration file and the tool shows them all in one place and notifies you about upcoming deposit closures, with a table of open date, close date, name, amount, interest and current amount. The command is a single one.

$ investments deposits

Non-exchange-traded unit investment funds are supported, but the program does not support specific fund providers along with their statements, and instead lets you specify all the operations manually in the configuration file. And the tax statement command reads broker statements and alters the .deX file created by the Russian tax program, adding the required information about income from stock selling, paid dividends and idle cash interest, with a separate document on recommendations for interacting with the Russian Federal Tax Service.

How the project is built

It is a Rust project, edition 2024, with the package manifest at version 8.4.0 and the command line binary defined at src/bin/investments/mod.rs. The dependency list is long and tells you what the tool leans on. Diesel is present as the database layer, with a diesel.toml and a migrations/ directory, and there is a build.rs. For the statement parsing there is calamine for spreadsheets and quick-xml for XML formats, csv for the CSV ones. For finance there is cusip and isin for identifiers, which matters because statements from different brokers name instruments differently, and the tool needs to match them. The HTTP stack is reqwest, the terminal output is prettytable-rs and ansi_term, the CLI is clap with shell completion support through clap_complete, the metrics are the prometheus crate, and the concurrency is tokio and rayon, with governor for rate limiting on the quote providers. The release profile turns on link time optimisation and a single codegen unit, and there is a clippy configuration with a list of allowed lints, several of them marked as temporary allowances with a FIXME comment to revisit them.

Editorial conclusion

investments fits a retail investor in Russia who holds several brokerage accounts and wants one number for real return after tax, commission and dividends, plus a rebalancing plan, rather than a portfolio app that shows a chart. It does not fit an investor outside Russia, because the brokers it parses, the tax treatment it applies and the tax statement it generates are all specific to the Russian market and its Federal Tax Service. It also does not fit someone who does not want to hand over their whole statement history, because the tool requires every statement from the account opening day, with the first one showing zero starting assets and no overlapping or missing periods. Before you run it, read the installation instructions, set up the config file with your broker, tax exemptions and API tokens for the quote providers, and keep the database backed up, since the sync command is what holds your current positions.

Frequently asked questions

Official sources

1. Issues
2. KonishchevDmitry/investments on GitHub
3. README
4. Releases