stocks-cli

A modular CLI tool for tracking stock portfolios and analyzing market data. Designed for extensibility and configurability.

Features

• Watchlists: Create and manage ticker lists, with automatic grabbers for major indices
• Portfolio tracking: Accounts, transactions (buy/sell/dividend/deposit/withdraw), USD/CAD conversion
• Cost basis & P&L: Weighted average cost, unrealized/realized P&L, dividend income tracking
• Technical analysis: SMA, EMA, DEMA, TEMA, MACD, RSI, Bollinger Bands
• Performance comparison: Normalized multi-ticker charts with multiple benchmarks
• Top/bottom analysis: Find best/worst performers from any watchlist
• Extensible architecture: Registry pattern for graphs and grabbers
• Full configurability: YAML config file + CLI overrides

Installation

# Clone and install with uv
git clone https://git.2027a.net/mathieu/stocks.git
cd stocks_machine
uv sync

# Verify installation
uv run stocks --help

Quick Start

#Add an alias to your shell config :
alias stocks='uv run --project /path/to/stocks_machine stocks'

# Grab S&P 500 tickers from Wikipedia
stocks grab run sp500

# Show top 10 performers over 1 year
stocks analyze top -w sp500 -p 1y -n 10

# Compare performance of specific tickers with benchmarks
stocks graph perf -t "AMD,NVDA,GOOG" -b "^GSPC:S&P 500, ^IXIC:NASDAQ" -p 1y

# Technical indicators for a single ticker vs benchmark
stocks graph indicators -t AMD -b "^GSPC:S&P 500" -p 6m -i "ema,macd,rsi"

Documentation

• Commands Reference: Detailed guide for all CLI commands.
• Configuration: Config file options, global flags, and reference syntax.
• Development: Testing, project structure, and extensibility.
• Manpage: Unix manpage format.