MarketForge - Global Market Intelligence CLI

A comprehensive command-line interface for real-time global market intelligence. MarketForge integrates multiple public APIs to provide professional-grade trading insights, portfolio management, technical analysis, and risk assessment for traders, investors, and financial analysts.

Overview

MarketForge aggregates data from six API sources (Polygon, CoinGecko, ExchangeRate, NewsAPI, REST Countries, World Bank) into a unified terminal-based intelligence platform. The tool delivers real-time monitoring, historical analysis, automated alerts, technical indicators, portfolio tracking, and comprehensive reporting capabilities.

Key Features

Real-Time Market Monitoring

Monitor stocks, cryptocurrencies, and foreign exchange rates with auto-refreshing terminal dashboards. Display live prices, percentage changes, trading volume, market capitalization, and trend indicators with configurable refresh intervals.

Deep Market Analysis with Technical Indicators

Perform statistical analysis on historical price data with support for natural language queries. Professional-grade technical indicators including RSI (Relative Strength Index), MACD (Moving Average Convergence Divergence), Bollinger Bands, Simple Moving Averages (SMA), and Exponential Moving Averages (EMA). Automated trading signal generation with confidence percentages and detailed reasoning. ASCII price charts for visual trend analysis.

Portfolio Management and Risk Analysis

Track investment positions across stocks and cryptocurrencies with real-time profit/loss calculations. Monitor portfolio diversification, concentration risk (Herfindahl index), volatility metrics, Sharpe ratios, and maximum drawdown. Maintain complete transaction history with cost basis tracking. View detailed risk analysis and position weighting.

Intelligent Alert System with Background Daemon

Configure price threshold alerts with automatic background monitoring via daemon process. Receive email notifications when conditions are met. Manage multiple alerts with persistent storage and comprehensive logging. Daemon runs every 5 minutes checking all configured alerts.

Geo-Economic Intelligence

Access country-specific economic data including GDP metrics, GDP growth rates, inflation indicators, population statistics, and currency exchange information from World Bank and REST Countries APIs.

Multi-Format Reporting

Generate and export market intelligence reports in PDF, JSON, or Markdown formats with customizable content, automatic timestamps, and comprehensive metadata.

Installation

Via npm (Global)

npm install -g marketforge-cli

Via npm (Local Project)

npm install marketforge-cli

From Source

git clone https://github.com/AryanSaxenaa/marketforge-cli.git
cd marketforge-cli
npm install
npm link

Configuration

Interactive Setup (Recommended)

Run the guided setup wizard:

marketforge init

The wizard will:

• Show which features need API keys and which work without
• Provide direct signup links for each API
• Let you skip any keys (add them later)
• Configure email notifications (optional)
• Create your .env file automatically
• Show personalized next steps based on your setup

All API keys are optional. Get started immediately with crypto and global features (no keys needed), then add other APIs as needed.

API Key Sources (All Free Tier Available)

| Service | Purpose | Free Tier | Required | Signup Link | |---------|---------|-----------|----------|-------------| | CoinGecko | Crypto data | 30 calls/min | No | No key needed | | REST Countries | Country data | Unlimited | No | No key needed | | World Bank | GDP/Economic data | Unlimited | No | No key needed | | Polygon.io | Stock market data | 5 calls/min | Optional | https://polygon.io/dashboard/signup | | NewsAPI.org | News headlines | 100 calls/day | Optional | https://newsapi.org/register | | ExchangeRate-API | Forex rates | 1500 calls/month | Optional | https://www.exchangerate-api.com/docs/free |

Manual Configuration

For users who prefer manual setup:

1. Copy the environment template:

cp .env.example .env

2. Edit .env and add your API keys:

POLYGON_API_KEY=your_key_here
NEWS_API_KEY=your_key_here
EXCHANGERATE_API_KEY=your_key_here

Quick Start

Option 1: Instant Start (No Setup Required)

# Install
npm install -g marketforge-cli

# Use immediately - works without any configuration
marketforge watch --crypto BTC,ETH
marketforge global --country US

Option 2: Full Setup (All Features)

# Install
npm install -g marketforge-cli

# Run interactive setup wizard
marketforge init

# Use all features
marketforge watch --crypto BTC,ETH --stock AAPL,TSLA
marketforge analyze --asset BTC --timeframe 7d --indicators --chart
marketforge portfolio --add AAPL,100,150
marketforge alert --threshold "BTC<100000" --email [email protected]

Command Reference

watch - Real-Time Market Monitoring

Monitor live market data with auto-refreshing terminal display.

# Monitor stocks
marketforge watch --stock AAPL,TSLA,GOOGL

# Monitor cryptocurrency
marketforge watch --crypto BTC,ETH,SOL

# Monitor forex
marketforge watch --currency USD,EUR,GBP

# Monitor everything with custom interval
marketforge watch --stock AAPL --crypto BTC --interval 15

Options:

• --stock, -s <symbols> - Comma-separated stock symbols
• --crypto, -c <symbols> - Comma-separated cryptocurrency symbols
• --currency, -f <codes> - Comma-separated currency codes
• --interval <seconds> - Refresh interval (default: 30)
• --verbose, -v - Show detailed information

analyze - Deep Market Analysis

Perform comprehensive statistical analysis with technical indicators.

# Natural language query
marketforge analyze --query "Bitcoin performance over 30 days"

# Specific asset analysis
marketforge analyze --asset AAPL --timeframe 1y

# With technical indicators
marketforge analyze --asset BTC --timeframe 30d --indicators

# With price chart
marketforge analyze --asset AAPL --timeframe 90d --chart

# Combined: indicators + chart
marketforge analyze --asset BTC --timeframe 7d --indicators --chart

Options:

• --query, -q <text> - Natural language query
• --asset, -a <symbol> - Asset symbol to analyze
• --timeframe, -t <period> - Analysis period (1d, 7d, 1m, 3m, 1y) - default: 30d
• --indicators - Display technical indicators and trading signals
• --chart - Display ASCII price chart
• --verbose, -v - Show detailed information

Technical Indicators Displayed:

• RSI (Relative Strength Index) - Overbought/oversold levels
• MACD - Momentum and trend direction
• Bollinger Bands - Volatility and price extremes
• SMA 50/200 - Moving average crossovers (golden cross/death cross)
• Support and Resistance - Key price levels
• Trading Signals - BUY/SELL/HOLD recommendations with confidence percentage

portfolio - Investment Portfolio Management

Track investment positions with real-time valuation and risk analysis.

# View portfolio summary
marketforge portfolio

# Add stock position (format: SYMBOL,QUANTITY,PRICE)
marketforge portfolio --add AAPL,100,150

# Add crypto position
marketforge portfolio --add BTC,0.5,50000 --type crypto

# Sell position
marketforge portfolio --sell AAPL,50,175

# View with comprehensive risk metrics
marketforge portfolio --risk

# View transaction history
marketforge portfolio --history --limit 50

Options:

• --add <data> - Add new position (format: SYMBOL,QUANTITY,PRICE)
• --sell <data> - Sell existing position (format: SYMBOL,QUANTITY,PRICE)
• --type <type> - Asset type for new positions (stock or crypto) - default: stock
• --history - Display transaction history
• --limit <number> - Number of transactions to display - default: 20
• --risk - Display comprehensive risk analysis
• --verbose, -v - Show detailed information

Risk Metrics Calculated:

• Concentration Risk - Herfindahl index for portfolio diversification
• Diversification Score - Normalized portfolio distribution (0-100)
• Portfolio Volatility - Annualized standard deviation of returns
• Sharpe Ratio - Risk-adjusted return measurement
• Maximum Drawdown - Largest peak-to-trough decline
• Position Weighting - Percentage allocation per asset

alert - Price Alert Management

Configure and manage automated price threshold notifications.

# Create price alert
marketforge alert --threshold "BTC<60000"

# Create alert with email notification
marketforge alert --threshold "AAPL>200" --email [email protected]

# List all configured alerts
marketforge alert --list

# Check alerts manually
marketforge alert --check

# Remove specific alert
marketforge alert --remove alert-1234567890

# Start background monitoring daemon
marketforge alert --start-daemon

# Check daemon status
marketforge alert --daemon-status

# View daemon logs
marketforge alert --daemon-logs

# Stop background daemon
marketforge alert --stop-daemon

Options:

• --threshold, -t <condition> - Alert condition (format: SYMBOLPRICE)
• --email, -e <address> - Email address for notifications
• --list, -l - Display all configured alerts
• --check, -c - Check all alerts immediately
• --remove, -r <id> - Remove alert by ID
• --start-daemon - Start background monitoring process
• --daemon-status - Display daemon process status
• --daemon-logs - Show daemon log output
• --stop-daemon - Stop background monitoring process
• --verbose, -v - Show detailed information

Background Daemon: The alert daemon runs as a detached background process, automatically checking all configured alerts every 5 minutes. Email notifications are sent when conditions are met.

global - Geo-Economic Intelligence

Access country-specific economic data and indicators.

# View country data
marketforge global --country US

# Compare multiple countries
marketforge global --country US,CN,IN

# Include GDP and economic indicators
marketforge global --country US --gdp

# Market correlations
marketforge global --country US --correlate

Options:

• --country, -c <codes> - Comma-separated country codes (e.g., US, CN, IN)
• --correlate - Display market correlations
• --gdp - Include GDP data from World Bank
• --verbose, -v - Show detailed information

report - Market Intelligence Reporting

Generate and export comprehensive market analysis reports.

# Generate JSON report
marketforge report --format json

# Generate PDF report
marketforge report --format pdf

# Generate Markdown report
marketforge report --format markdown

# Custom output path
marketforge report --format json --output ./reports/market-analysis.json

Options:

• --format, -f <type> - Report format (pdf, json, markdown) - default: pdf
• --output, -o <path> - Custom output file path
• --verbose, -v - Show detailed information

init - Configuration Wizard

Interactive setup wizard for API credentials and email notifications.

marketforge init

Technical Indicators Reference

RSI (Relative Strength Index)

Momentum oscillator measuring speed and magnitude of price changes. Values above 70 indicate overbought conditions, below 30 indicate oversold. Default: 14-period window with Wilder smoothing.

MACD (Moving Average Convergence Divergence)

Trend-following momentum indicator showing relationship between two EMAs. Configuration: 12-period fast EMA, 26-period slow EMA, 9-period signal line. Bullish when MACD crosses above signal line.

Bollinger Bands

Volatility indicator with middle band (20-period SMA) and upper/lower bands at 2 standard deviations. Price touching upper band suggests overbought; lower band suggests oversold.

Simple Moving Averages (SMA)

Arithmetic mean of closing prices. Golden cross (50 SMA crossing above 200 SMA) indicates bullish trend; death cross indicates bearish trend.

Trading Signals

Combines multiple indicators for actionable recommendations: STRONG BUY, BUY, HOLD, SELL, STRONG SELL. Each signal includes confidence percentage and detailed reasoning.

Portfolio Risk Metrics Reference

Concentration Risk (Herfindahl Index)

Measures diversification by summing squared position weights. Values above 0.3 indicate high concentration risk.

Sharpe Ratio

Risk-adjusted return metric. Values above 1.0 considered good, above 2.0 considered excellent.

Maximum Drawdown

Largest peak-to-trough decline in portfolio value. Important for understanding downside risk.

Architecture

marketforge-cli/
├── bin/
│   └── marketforge.js          # CLI entry point
├── src/
│   ├── commands/                # Command implementations
│   │   ├── watch.js            # Real-time monitoring
│   │   ├── analyze.js          # Market analysis with indicators
│   │   ├── alert.js            # Alert management and daemon
│   │   ├── global.js           # Geo-economic intelligence
│   │   ├── report.js           # Report generation
│   │   ├── portfolio.js        # Portfolio management
│   │   └── init.js             # Configuration wizard
│   ├── apis/                    # API client wrappers
│   │   ├── polygon.js          # Stock market data
│   │   ├── coingecko.js        # Cryptocurrency data
│   │   ├── exchangerate.js     # Forex rates
│   │   ├── newsapi.js          # News headlines
│   │   ├── restcountries.js    # Country data
│   │   └── worldbank.js        # GDP and economic indicators
│   └── lib/                     # Utility libraries
│       ├── api-client.js       # Base API client with retry logic
│       ├── cache.js            # File-based caching
│       ├── utils.js            # Helper functions
│       ├── nlparser.js         # Natural language query parser
│       ├── alert-daemon.js     # Background alert monitoring
│       ├── daemon-runner.js    # Daemon process management
│       ├── portfolio-manager.js # Portfolio tracking and risk
│       ├── technical-indicators.js # RSI, MACD, Bollinger Bands
│       └── chart-utils.js      # ASCII chart generation
├── config/
│   └── defaults.js
├── package.json
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE

Data Sources and Attribution

Polygon.io

Real-time and historical stock market data. Free tier: 5 API calls per minute.

CoinGecko

Comprehensive cryptocurrency data. Free tier: 30 API calls per minute. No API key required.

ExchangeRate-API

Foreign exchange rates with historical data. Free tier: 1500 API calls per month.

NewsAPI.org

Aggregated news headlines from global sources. Free tier: 100 API calls per day.

REST Countries

Comprehensive country data and demographics. No rate limits. No API key required.

World Bank

Economic indicators including GDP and growth rates. No API key required.

Troubleshooting

API Rate Limit Exceeded

The tool automatically uses cached data when available. Consider upgrading to paid API tiers for higher limits, or reduce request frequency.

Missing API Key

Features requiring API keys will gracefully degrade. Cryptocurrency and country data features work without any configuration. Add API keys via marketforge init.

Email Notifications Not Working

Verify SMTP credentials in .env file. For Gmail users: Enable "Less secure app access" or use app-specific password.

Alert Daemon Not Starting

Ensure no other daemon instance is running. Check status with marketforge alert --daemon-status. View logs with marketforge alert --daemon-logs.

Portfolio Data Not Persisting

Verify write permissions for portfolio.json file. Check disk space availability.

Development and Contributing

Contributions are welcome. Please follow the guidelines in CONTRIBUTING.md.

Running from Source

git clone https://github.com/AryanSaxenaa/marketforge-cli.git
cd marketforge-cli
npm install
npm link
marketforge --version

Contributing Guidelines

• Fork the repository and create a feature branch
• Write clear commit messages
• Add tests for new functionality
• Update documentation
• Submit pull request with detailed description

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the MIT License. See LICENSE file for details.

Security Considerations

• API keys are stored in .env file - never commit to version control
• Email credentials for SMTP stored locally - use app-specific passwords
• Portfolio data stored in local JSON file - ensure appropriate permissions
• Alert daemon runs with user privileges - no elevated permissions required

Performance

• Real-time data refresh: 10-30 second intervals (configurable)
• API response caching: 5 minutes for real-time, 1 hour for historical
• Portfolio calculations: O(n) complexity for n positions
• Technical indicators: O(n) complexity for n data points
• Memory usage: Approximately 50-100 MB during operation

Version History

Version 1.0.0 (Current)

• Initial release with 7 core commands
• 6 API integrations
• Portfolio management with risk metrics
• Technical indicators and trading signals
• Background alert daemon
• Natural language query parsing
• ASCII chart visualization
• Comprehensive documentation

See CHANGELOG.md for complete version history.

Support and Contact

For bug reports, feature requests, or questions:

• GitHub Issues: https://github.com/AryanSaxenaa/marketforge-cli/issues
• Repository: https://github.com/AryanSaxenaa/marketforge-cli

Acknowledgments

This project integrates data from multiple public APIs:

• Polygon.io for stock market data
• CoinGecko for cryptocurrency data
• ExchangeRate-API for forex data
• NewsAPI.org for news headlines
• REST Countries for country data
• World Bank for economic indicators

Disclaimer

This tool is provided for informational purposes only. It is not financial advice. Users should conduct their own research and consult with qualified financial advisors before making investment decisions. Past performance does not guarantee future results. Trading and investing carry risk of loss.

Author

Aryan Saxena

Repository

https://github.com/AryanSaxenaa/marketforge-cli

Portfolio Risk Metrics Reference

Concentration Risk (Herfindahl Index)

Measures diversification by summing squared position weights. Values above 0.3 indicate high concentration risk.

Sharpe Ratio

Risk-adjusted return metric. Values above 1.0 considered good, above 2.0 considered excellent.

Maximum Drawdown

Largest peak-to-trough decline in portfolio value. Important for understanding downside risk.

Architecture

marketforge/
├── bin/
│   └── marketforge.js       # CLI entry point
├── src/
│   ├── commands/            # Subcommand handlers
│   │   ├── watch.js
│   │   ├── analyze.js
│   │   ├── alert.js
│   │   ├── global.js
│   │   └── report.js
│   ├── lib/
│   │   ├── api-client.js    # Base API client
│   │   ├── cache.js         # Caching layer
│   │   └── utils.js         # Utilities
│   └── apis/                # API wrappers
│       ├── polygon.js
│       ├── coingecko.js
│       ├── exchangerate.js
│       ├── newsapi.js
│       └── restcountries.js
├── config/
│   └── defaults.js          # Default configuration
└── .env                     # API keys (not in repo)

Use Cases

• Day Traders: Monitor multiple assets with real-time alerts
• Startup Founders: Track market trends and competitor stock movements
• Financial Analysts: Generate comprehensive reports with correlations
• Global Investors: Understand geo-economic context for international investments
• Researchers: Export market data for academic analysis

Rate Limiting and Caching

• Implements aggressive caching (5-min for real-time, 1-hour for historical)
• Automatic retry with exponential backoff
• Graceful degradation if APIs fail
• Displays remaining quota in verbose mode

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Built With

• Node.js - Runtime environment
• Commander.js - CLI framework
• Axios - HTTP client
• Various npm packages for terminal UI

Development

This project was developed using GitHub Copilot CLI for accelerated development, intelligent code generation, and rapid API integration.

Support

For issues or questions, please open an issue on the GitHub repository.

Acknowledgments

Created for the GitHub + DEV Copilot CLI Hackathon 2026