Portfolio

Investment portfolio manager. Add and remove holdings, list positions, analyze allocation weights, generate rebalance suggestions against target weights, and calculate performance returns over configurable time periods. All data is stored locally in JSON files — no external API calls required.

Commands

Data Storage

All data is stored locally in ~/.portfolio/:

• holdings.json — Array of current positions, each with ticker, quantity, avg_price, and date_added
• transactions.json — Array of all buy/sell transactions with type, ticker, quantity, price, and date

Both files are auto-created as empty JSON arrays ([]) on first use. The add command automatically merges duplicate tickers by recalculating the weighted average price.

Requirements

• bash (4.0+)
• python3 (standard library only — json, os, sys, datetime)
• No external APIs, no pip packages, no network access needed

When to Use

1. Tracking purchases — When you buy stocks, ETFs, or crypto and want to record ticker, quantity, and price with automatic cost-basis averaging
2. Reviewing holdings — When you need a quick snapshot of your current portfolio in table, JSON, or CSV format
3. Allocation analysis — When you want to see how your portfolio is weighted across assets, with percentage breakdowns and visual bars
4. Rebalancing — When you need buy/sell recommendations to reach target allocation weights (e.g., AAPL:40,GOOG:30,BTC:30), with configurable drift thresholds
5. Performance tracking — When you want to calculate total invested, total sold, current value, and gain/loss percentage over a specific time period (1 day to all-time)

Examples

# Add 100 shares of AAPL at $150.50, purchased on Jan 15, 2024
bash scripts/script.sh add AAPL 100 150.50 --date 2024-01-15

# Add 0.5 BTC at $42,000 (today's date auto-applied)
bash scripts/script.sh add BTC 0.5 42000

# Sell 50 shares of AAPL (partial sell)
bash scripts/script.sh remove AAPL --quantity 50