As a developer, managing a stock portfolio can be a daunting task, especially when it comes to tracking prices, calculating gains, and making informed investment decisions. To address this problem, I created Stock Tracker CLI, a command-line interface tool built using Python. In this post, we'll delve into the technical aspects of the project, exploring the solutions and technologies used to bring this tool to life. The initial commit, version 0.1.0, lays the foundation for a robust and scalable application.
Technical Problem and Solution ---------------------------------
The primary challenge was to design a system that could fetch real-time stock data, calculate portfolio performance, and provide insightful reports. To tackle this, I employed a modular architecture, separating concerns into distinct modules. The `data_fetcher.py` module is responsible for retrieving stock data from external APIs, while `portfolio.py` handles portfolio management and calculations. The `reporting.py` module generates detailed reports, providing users with a clear understanding of their portfolio's performance. By using a modular approach, the codebase remains maintainable, and new features can be added easily. For example, the `data_fetcher.py` module uses the `yfinance` library to fetch stock data, demonstrating the use of third-party libraries to simplify development.
Technologies and Patterns Used ---------------------------------
Stock Tracker CLI leverages several technologies and patterns to ensure a robust and efficient application. The project uses Python 3, taking advantage of its extensive libraries and frameworks. The `pyproject.toml` file manages dependencies, ensuring reproducibility and ease of installation. The `Dockerfile` enables containerization, allowing users to run the application in a isolated environment. The `logging_config.py` module configures logging, providing valuable insights into the application's behavior. By using established patterns and technologies, the project ensures a high degree of maintainability and scalability. For instance, the use of a `.env.example` file demonstrates how to manage environment variables, a crucial aspect of securing sensitive data.
Architecture Decisions and Code Concepts ------------------------------------------
One of the key architecture decisions was to use a command-line interface (CLI) as the primary interaction point. This decision was driven by the need for a simple, yet powerful, user interface. The `cli.py` module handles user input, parsing commands and arguments using the `argparse` library. The `stock_tracker.py`
A command-line tool to track your stock portfolio and get AI-powered investment analysis.
pip install stock-tracker-cli
git clone https://github.com/Chukwuebuka-2003/stock_cli.git
cd stock_cli
pip install -e .
# Setup Groq API key for AI analysis
stock-tracker setup-ai
# Setup Alpha Vantage API key for stock data
stock-tracker setup-alpha-vantage
# Setup email settings (optional, for email reports)
stock-tracker setup-email
Get Free API Keys:
# Add a stock position
stock-tracker add AAPL 10 150.00
# Arguments: SYMBOL QUANTITY PURCHASE_PRICE
stock-tracker add MSFT 5 300.00
stock-tracker add GOOGL 3 2800.00
# View portfolio report in terminal
stock-tracker report
# Get AI-powered analysis
stock-tracker ai-report
# Send AI report via email
stock-tracker ai-report --email recipient@example.com
# Add a stock position
stock-tracker add <SYMBOL> <QUANTITY> <PURCHASE_PRICE>
# Remove a stock position
stock-tracker remove <SYMBOL>
# Generate plain text report
stock-tracker report
# Generate AI-powered analysis report
stock-tracker ai-report [--email EMAIL]
# Configure Groq API key
stock-tracker setup-ai
# Configure Alpha Vantage API key
stock-tracker setup-alpha-vantage
# Configure email settings
stock-tracker setup-email
Stock Portfolio Report
Generated on: 2025-11-09 10:30:00
╔════════╦══════════╦════════════════╦═══════════════╦════════════╦═════════════════╗
║ Symbol ║ Quantity ║ Purchase Price ║ Current Price ║ Value ║ Gain/Loss (%) ║
╠════════╬══════════╬════════════════╬═══════════════╬════════════╬═════════════════╣
║ AAPL ║ 10.0 ║ $150.00 ║ $178.50 ║ $1,785.00 ║ +$285.00 (+19%) ║
║ MSFT ║ 5.0 ║ $300.00 ║ $385.20 ║ $1,926.00 ║ +$426.00 (+28%) ║
║ GOOGL ║ 3.0 ║ $2,800.00 ║ $2,950.00 ║ $8,850.00 ║ +$450.00 (+5%) ║
╚════════╩══════════╩════════════════╩═══════════════╩════════════╩═════════════════╝
Portfolio Summary:
Total Value: $12,561.00
Total Gain/Loss: +$1,161.00 (+10.2%)
# Build the image
docker-compose build
# Run one-time report
docker-compose run stock-tracker stock-tracker report
# Run with scheduled reports (daily at 4:30 PM UTC on weekdays)
docker-compose up -d cron
Create a .env file:
GROQ_API_KEY=your_groq_api_key
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key
EMAIL_SMTP_SERVER=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USERNAME=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
EMAIL_RECIPIENT=recipient@example.com
The CLI stores data in platform-specific directories:
~/.config/StockTrackerCLI/ and ~/.local/share/StockTrackerCLI/~/Library/Application Support/StockTrackerCLI/%LOCALAPPDATA%\StockTrackerCLI\config.json - API keys and email settingspositions.json - Your stock positionscache.json - Cached stock data (15-minute expiry)logs/stock_tracker.log - Application logsFor Gmail users, you'll need to use an App Password:
stock-tracker setup-emailMIT License - see LICENSE file for details
Chukwuebuka Ezeokeke - GitHub
Contributions are welcome! Please feel free to submit a Pull Request.
Found a bug? Please report it on the GitHub Issues page.