A command line tool for managing financial investment portfolios. https://crates.io/crates/portfolio_rs
  • Rust 99.6%
  • Nix 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 17:27:04 +01:00
.cargo build: add cargo coverage alias and llvm-cov to the dev shell 2026-11-03 09:39:48 +01:00
.github ci: pin the coverage job to Rust 1.99.1 (#486) 2026-11-17 08:13:40 +01:00
docs feat(mcp): name the stale snapshot behind a stale get_performance 2026-11-01 21:55:55 +01:00
img docs: slim down README, move reference material to docs/, drop outdated images 2026-10-28 08:51:53 +01:00
src fix: flush backups through a writable handle on Windows (#476) 2026-11-06 16:32:56 +01:00
templates feat: add agent-native finance features 2026-07-05 11:20:04 +02:00
tests test(mcp): cover the MCP server modules to 100% lines 2026-11-03 09:39:48 +01:00
.envrc build: add nix flake 2025-07-22 10:57:46 +02:00
.gitignore chore: ignore .claude/ 2026-10-28 03:38:07 +01:00
AGENTS.md ci: enforce 100% line coverage in CI and for agents 2026-11-03 09:39:48 +01:00
Cargo.lock chore(deps): bump uuid from 1.29.0 to 1.29.2 (#484) 2026-11-17 09:19:11 +01:00
Cargo.toml chore(deps): bump jsonschema from 0.60.2 to 0.61.2 (#483) 2026-11-17 09:04:03 +01:00
CLAUDE.md ci: enforce 100% line coverage in CI and for agents 2026-11-03 09:39:48 +01:00
example_data.json style: format 2025-12-05 22:48:31 +01:00
flake.lock chore: update flake.lock 2026-11-17 17:27:04 +01:00
flake.nix build: add cargo coverage alias and llvm-cov to the dev shell 2026-11-03 09:39:48 +01:00
LICENSE Create LICENSE 2022-09-20 14:58:31 +02:00
README.md fix: a manual holding without purchases is one item 2026-11-01 21:06:31 +01:00
rustfmt.toml chore: add release profile optimizations and rustfmt config 2026-04-25 17:08:49 +02:00

portfolio_rs logo
build status badge

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_rs or nix 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/k and press e to 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