Candlestick-CLI 📈

Creating professional candlestick charts directly in your terminal, built with modern TypeScript and designed for developers who need real-time financial data visualization without leaving their terminal environment.

See CHANGELOG.md for version history and updates.

---

✨ Features

• 🎨 Unicode Candlestick Charts - High-quality visualization with Unicode characters
• 📊 Live Market Data - Real-time data from cryptocurrency exchanges via CCXT
• 🎛️ Customizable Colors - Set custom bullish/bearish colors with RGB values
• 📏 Auto-fit Terminal - Automatically adjusts to terminal size
• 📈 Volume Pane - Optional volume bars display with Unicode characters
• 🎯 Price Highlighting - Highlight specific price levels with custom colors
• 🔧 Flexible API - Use as library or standalone CLI tool
• ⚡ TypeScript - Full type safety and modern development
• 🖥️ Terminal Optimized - Designed specifically for terminal display
• 🚀 CCXT Integration - Built-in support for multiple trading exchanges
• 📤 Export Support - Export charts as PNG images or text files
• 🔄 Watch Mode - Real-time updates with customizable intervals
• 📱 Smart Scaling - Auto-fit, fixed, and price-based scaling modes
• 🎨 Theme Support - Dark and light background themes for exports
• 📊 High-Resolution Exports - Scalable PNG exports with custom quality
• 📈 Volume Analysis - Volume pane with bearish/bullish color coding
• 🌐 Multiple Timeframes - Support for 1m to 1M timeframes

---

📦 Installation

npm install @neabyte/candlestick-cli

Or clone and install locally:

git clone https://github.com/NeaByteLab/Candlestick-CLI.git
cd Candlestick-CLI
npm install

---

🚀 Quick Start

📋 Library Usage

import { Chart } from '@neabyte/candlestick-cli'

const candles = [
  { open: 100, high: 105, low: 99, close: 103, volume: 1000, timestamp: 1640995200000, type: 1 },
  { open: 103, high: 108, low: 102, close: 106, volume: 1200, timestamp: 1640998800000, type: 1 },
  { open: 106, high: 110, low: 104, close: 109, volume: 1500, timestamp: 1641002400000, type: 1 }
]

const chart = new Chart(candles, { title: 'BTC/USDT', width: 120, height: 30 })
chart.draw() // Renders beautiful Unicode candlestick chart in terminal

💻 CLI Usage

Global Installation (Recommended)

# Install globally
npm install -g @neabyte/candlestick-cli

# Display chart from CSV file
candlestick-cli -f data.csv -t "BTC/USDT"

# Display chart from JSON file with custom colors
candlestick-cli -f data.json --bear-color "#ff6b6b" --bull-color "#51cf66"

# Display chart without volume pane
candlestick-cli -f data.csv --no-volume

# Display chart with custom dimensions
candlestick-cli -f data.csv -w 120 -h 30

# Live market data from cryptocurrency exchange
candlestick-cli -s BTC/USDT --timeframe 4h --limit 200

# Perpetual futures trading
candlestick-cli -s BTC/USDT:USDT --timeframe 1h --limit 150

# Watch mode with real-time updates
candlestick-cli -s BTC/USDT --watch --interval 30

# Export chart as PNG image (dark theme)
candlestick-cli -s BTC/USDT -o chart.png --background dark

# Export chart as PNG image (light theme)
candlestick-cli -s BTC/USDT -o chart.png --background light

# Export chart as text file
candlestick-cli -f data.csv -o chart.txt

# Custom volume height
candlestick-cli -f data.csv --volume-height 12

# Multiple timeframes
candlestick-cli -s BTC/USDT --timeframe 1m --limit 100
candlestick-cli -s BTC/USDT --timeframe 15m --limit 200
candlestick-cli -s BTC/USDT --timeframe 1d --limit 50

**Note**: Export dimensions are automatically optimized for best quality.

Local Installation

# Run with npx (if not installed globally)
npx @neabyte/candlestick-cli -f data.csv -t "BTC/USDT"

# Live data with npx
npx @neabyte/candlestick-cli -s BTC/USDT --timeframe 1h --limit 100

---

📚 Documentation

📖 Complete API Reference

• API Reference - API documentation with all classes, methods, and types
• CLI Reference - Complete command-line interface documentation
• Examples Guide - Detailed usage examples and patterns
• Documentation Home - Overview of all available documentation

🎯 Key Documentation Sections

• Chart Class - Main chart rendering and configuration
• CLI Interface - Command-line tool usage and options
• Data Processing - CSV/JSON parsing and real-time data
• CCXT Integration - Live market data from cryptocurrency exchanges
• Export Features - PNG image and text file export capabilities
• Error Handling - Custom error types and validation
• TypeScript Types - Complete type definitions and interfaces

---

🔗 Related Projects

• Rust Version by Julien-R44
• Python Version by BoboTiG

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines on:

• Development setup and workflow
• Code style and standards
• Testing requirements
• Areas for contribution
• Pull request process

---

📄 License

MIT License - see LICENSE for details.