Portfolio Tracker

A CLI tool for tracking stock and crypto portfolios with real-time prices, P&L, and dividend tracking.

When to Use This Skill

Use this skill when you need to:

• Track stock and crypto holdings locally
• Get real-time prices and P&L
• Track dividend yields, Yield on Cost, and projected income
• View upcoming ex-dividend dates
• Manage multiple portfolios
• Export portfolio data to CSV

Tools

This skill provides the following capabilities:

1. List Holdings

Show all holdings with current values and P&L.

Command:

npx tsx portfolio.ts list

2. Add Holding

Add a new stock or crypto holding.

Command:

npx tsx portfolio.ts add <symbol> <quantity> <price> <name> [type]

Examples:

npx tsx portfolio.ts add AAPL 10 150 "Apple Inc." stock
npx tsx portfolio.ts add BTC 0.5 45000 Bitcoin crypto

3. Sell Holding

Sell shares using FIFO (First-In-First-Out) cost basis method.

Command:

npx tsx portfolio.ts sell <symbol> <quantity> <price> [date]

Examples:

npx tsx portfolio.ts sell AAPL 5 180 2025-06-01
npx tsx portfolio.ts sell BTC 0.25 50000

4. Transaction History

View sell history for all holdings or a specific symbol.

Command:

npx tsx portfolio.ts history [symbol]

Examples:

npx tsx portfolio.ts history
npx tsx portfolio.ts history AAPL

5. P&L Summary

Show both realized and unrealized profit/loss.

Command:

npx tsx portfolio.ts pnl

6. Dividend Tracking

View detailed dividend information for stock holdings including yield, Yield on Cost (YOC), and projected annual income.

Command:

npx tsx portfolio.ts dividends

7. Dividend Summary

Show portfolio-level dividend summary: total projected income, weighted average yield, and Yield on Cost.

Command:

npx tsx portfolio.ts dividend-summary

Output includes:

• Total projected annual income
• Monthly/quarterly income estimates
• Weighted average yield across all holdings
• Portfolio Yield on Cost
• Count of dividend-paying stocks

8. Dividend Calendar

View upcoming ex-dividend dates for your holdings.

Command:

npx tsx portfolio.ts calendar [days]

Examples:

npx tsx portfolio.ts calendar       # Next 30 days
npx tsx portfolio.ts calendar 60    # Next 60 days

9. List with Dividends

The list command automatically fetches dividend data. Use --no-dividends flag to skip.

Commands:

npx tsx portfolio.ts list           # With dividend info
npx tsx portfolio.ts list --no-dividends  # Skip dividends

10. Remove Holding

Remove a holding by symbol.

Command:

npx tsx portfolio.ts remove <symbol>

11. Portfolio Value

Show total portfolio value and P&L.

Command:

npx tsx portfolio.ts value

12. Manage Portfolios

List, switch, or create portfolios.

Commands:

npx tsx portfolio.ts portfolios
npx tsx portfolio.ts switch "Portfolio Name"
npx tsx portfolio.ts create "New Portfolio"

Tip: After running npm link, you can use the shorter portfolio command instead of npx tsx portfolio.ts.

Installation

First, install the required dependencies:

npm install

This will install all necessary packages including TypeScript runtime (tsx), Next.js, React, and other dependencies listed in package.json.

Optional: Link the CLI globally for easier access:

npm link

After linking, you can use portfolio instead of npx tsx portfolio.ts .

NPM Scripts

npm run dev        # Start web UI (optional)
npm run build      # Build for production

Web UI (Optional)

You can also run an optional web interface with full dividend tracking support:

npm run dev

Then open http://localhost:3000

Web UI Features:

• Real-time portfolio value and P&L tracking
• Dividend summary cards (annual income, weighted yield, YOC, upcoming dates)
• Detailed dividend breakdown table per stock
• Visual calendar of upcoming ex-dividend dates
• Interactive pie chart for portfolio allocation

Data Storage

Portfolio data is stored locally in data/portfolio.json. The data file is created automatically on first run with an empty portfolio.

Features

• Real-time stock prices via Yahoo Finance API
• Real-time crypto prices via CoinGecko API
• Multiple portfolio support
• P&L tracking per holding
• Dividend tracking (yield, YOC, projected income, ex-dates)
• CLI and optional web interface