- Rust 99.6%
- Nix 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .cargo | ||
| .github | ||
| docs | ||
| img | ||
| src | ||
| templates | ||
| tests | ||
| .envrc | ||
| .gitignore | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CLAUDE.md | ||
| example_data.json | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| README.md | ||
| rustfmt.toml | ||

Local-first portfolio management for humans and AI agents, written in Rust.
portfolio_rs is an interactive terminal UI for tracking investment
portfolios: your total value at a glance, allocation by asset class, and a
balances table you can edit in place. The same data is available as CLI
commands, and AI agents get a safe, local view of your finances:
machine-readable investment policies, policy-aware reviews, rebalancing
simulations, durable records (diary, decisions, reports), a portable agent
skill, a read-only MCP server and a local HTTP API. GUIs can embed it as a
Rust library.
This project is the modern successor of finance.
Installation
- nixpkgs:
nix-shell -p portfolio_rsornix run nixpkgs#portfolio_rs - pkgx:
pkgx portfolio_rs - cargo:
cargo install portfolio_rs
Quick start
Simple mode. Create a JSON file with your positions (see example data for the schema), then launch the TUI:
portfolio_rs my_positions.json
A position's Amount is its number of units when it has a Ticker, and the
balance for cash. A position with neither is a manual holding whose Amount
is its value: without Purchases it counts as one item (quantity 1) and shows
no price; with Purchases its quantity is the sum of the purchase quantities.
A positions file that does not parse is never shown as an empty portfolio:
every command that reads it prints Error parsing positions in <file>: <reason> at line L column C and exits with code 2, like validate, and snapshot
writes nothing.
Workspace mode. For policies, diary, decisions, and reports, create a workspace:
portfolio_rs init-workspace my-portfolio
portfolio_rs policy init --strategy balanced-growth my-portfolio
portfolio_rs context my-portfolio/positions.json
This creates an INVESTMENT_POLICY.md (your financial constitution), a
machine-readable portfolio/policy.toml, folders for diary entries, decision
records, theses, and reports, agent instructions (AGENTS.md, CLAUDE.md),
and a .gitignore that keeps your private data out of git.
The TUI
Run portfolio_rs with a positions file (or none, to use the one from your
config) and you land in the TUI. It has two tabs:
- Overview & Allocation: total portfolio value, an allocation bar chart and the percentage per asset class.
- Balances: every position with amount and current value. Select one with
j/kand presseto edit its amount; the change is saved to your file.
Switch tabs with h/l, Tab or 1/2, quit with q. Start on a tab with
--tab balances, and hide parts of the screen with --disable (see
docs/tui.md).
Commands
| Command | Description |
|---|---|
portfolio_rs [FILE] |
Interactive TUI (default) |
balances [FILE] |
Balances table (quantity, cost, value, PnL) |
allocation [FILE] |
Allocation pie chart and breakdown |
performance [FILE] |
Performance metrics (YTD, total return) |
sort [FILE] |
Positions sorted by value (display only) |
context [FILE] |
Agent-friendly portfolio briefing (Markdown/JSON) |
review [FILE] |
Policy-aware review: drift, violations, actions |
simulate [FILE] |
Rebalancing what-if scenarios (never trades) |
validate [FILE] |
Validate a portfolio JSON file |
policy init/validate |
Create/check a machine-readable policy.toml |
decision draft |
Draft a structured decision record |
report weekly |
Generate a weekly Markdown report |
doctor [DIR] |
Workspace health check |
init-workspace [DIR] |
Create a new finance workspace |
agent init/skill |
Agent instructions + portable skill management |
api |
Local HTTP API server |
mcp |
Read-only MCP server for AI agents (stdio) |
snapshot |
Record today's valuation for get_performance |
config |
Show config file location |
components |
List TUI components for --disable |
Without a file argument, commands use the portfolio file (or workspace) from
your config. Run portfolio_rs <COMMAND> --help for details.
Documentation
- TUI: tabs, navigation, editing, hiding components
- AI and agent integration: JSON output, policies, agent skill
- MCP server: tools, resources, price cache, snapshots, client setup
- HTTP API: endpoints, auth, local-only guarantees
- Library usage: embedding
AppStatein a GUI - Quotes, currencies and returns: quote sources, FX,
performance - Configuration: config file, GPG-encrypted portfolios