portfolio

my-portfolio

A TypeScript/Bun CLI for portfolio tracking, backed by PostgreSQL.

Features

• Pure JSON Output: All commands emit JSON envelopes, making the CLI ideal for scripting, automation, and downstream integrations.
• PostgreSQL Powered: All financial data — transactions, daily returns, price cache, and FIFO cost basis — lives in PostgreSQL. The CLI never recomputes what the database already owns.
• Deterministic Valuation: Time-Weighted Return (TWR) is the primary portfolio return metric. Read commands consume cached prices and FX only; they never trigger network calls.
• Comprehensive Tracking: Supports standard trade actions (BUY, SELL), cash flows (DEPOSIT, WITHDRAW, TRANSFER), income (DIVIDEND, INTEREST), expenses (FEE, TAX), and currency exchanges.
• Multi-Currency: Base currency is USD, with FX-converted reporting and FIFO cost basis for international assets.

Prerequisites

• Bun >= 1.3 — the JavaScript/TypeScript runtime that executes the CLI directly from source. No build step is required.
• PostgreSQL >= 14 — local install (e.g. brew install postgresql@16) or a hosted instance (Supabase, Neon, etc.).
• psql (optional, recommended) — for one-time schema bootstrap before first portfolio health.

Bun runs the TypeScript source directly via the shebang in portfolio-ts/src/cli.ts, so a separate tsc build is not required for normal use. bun run typecheck is available for static validation.

Installation

# Clone the repository
git clone <repository-url>
cd my-portfolio

# Install CLI dependencies (Bun reads bun.lock)
cd portfolio-ts
bun install
cd ..

That's it for the runtime. The CLI source ships as TypeScript and is executed by Bun directly.

Configure the database

The CLI talks to PostgreSQL through a single environment variable: PORTFOLIO_DB_URL.

You can set it in your shell, or — more conveniently — drop it in a .env file. The CLI auto-loads .env from the current working directory or any parent directory before reading PORTFOLIO_DB_URL (issue #142), so you usually do not need to export anything.

Create a .env at the repository root (or copy from .env.example):

# .env  (gitignored — never commit real credentials)
PORTFOLIO_DB_URL=postgresql://postgres:postgres@localhost:5432/portfolio

Or for a hosted instance:

PORTFOLIO_DB_URL='postgresql://postgres:[YOUR-PASSWORD]@db.<project-ref>.supabase.co:5432/postgres?sslmode=require'

One-time schema bootstrap

The CLI's init command only verifies that the schema is in place — it does not create tables. On a fresh database, apply the SQL files under portfolio_db/sql/ once:

psql "$PORTFOLIO_DB_URL" -v ON_ERROR_STOP=1 -f portfolio_db/sql/schema.sql
psql "$PORTFOLIO_DB_URL" -v ON_ERROR_STOP=1 -f portfolio_db/sql/functions.sql
psql "$PORTFOLIO_DB_URL" -v ON_ERROR_STOP=1 -f portfolio_db/sql/procedures.sql
psql "$PORTFOLIO_DB_URL" -v ON_ERROR_STOP=1 -f portfolio_db/sql/views.sql
psql "$PORTFOLIO_DB_URL" -v ON_ERROR_STOP=1 -f portfolio_db/sql/triggers.sql

The portfolio_db/sql/ files are pure PostgreSQL and remain the source of truth for the schema.

Quick start

There are two equivalent ways to invoke the CLI.

1. From the portfolio-ts/ directory (development form):

cd portfolio-ts
bun src/cli.ts --help          # or: bun start -- --help
bun src/cli.ts health

2. As the portfolio binary:

A wrapper script lives at bin/portfolio at the repo root and can be invoked directly:

./bin/portfolio --help
./bin/portfolio health

The package.json also declares "bin": {"portfolio": "src/cli.ts"}, so after bun link (run inside portfolio-ts/) the portfolio command is on your PATH globally:

cd portfolio-ts
bun link                      # one-time, registers the `portfolio` bin
portfolio --help
portfolio health

All examples below use the portfolio form. Substitute bun src/cli.ts (run from portfolio-ts/) or ./bin/portfolio (run from the repo root) if you have not linked the bin.

Running the CLI against the Dockerized service

Use your local bun invocation when you want to target your own PORTFOLIO_DB_URL during development. Use docker compose -f portfolio-ts/docker-compose.yml exec portfolio bun run src/cli.ts <command> [flags] when you want to run against the running container's PostgreSQL database.

Examples:

docker compose -f portfolio-ts/docker-compose.yml exec portfolio bun run src/cli.ts summary
docker compose -f portfolio-ts/docker-compose.yml exec portfolio bun run src/cli.ts backup push
docker compose -f portfolio-ts/docker-compose.yml exec portfolio bun run src/cli.ts cloudflare publish