Sprout Analytics CLI

Professional command-line tool for comprehensive social media performance analysis using Sprout Social data with AI-powered strategic insights.

🚀 Features

• Multi-Platform Analysis: Instagram, LinkedIn, YouTube, TikTok, X/Twitter, Facebook, Threads
• Flexible Time Comparisons: Week-over-week, custom periods, year-over-year
• AI-Powered Insights: GPT-5 strategic recommendations and optimization guidance
• Professional Reports: Clean markdown output with executive summaries and detailed metrics
• Data Export: Comprehensive data export in readable markdown format
• Platform-Specific Analysis: Tailored insights for each social media platform

📋 Table of Contents

• Quick Start
• Installation
• Usage
• Data Requirements
• Output Examples
• AI Integration
• Platform Analysis
• Contributing
• License

⚡ Quick Start

# 1. Clone the repository
git clone https://github.com/yavzius/sprout-analytics-cli.git
cd sprout-analytics-cli

# 2. Run the setup script
./install.sh

# 3. Add your Sprout Social data
cp your_sprout_export.csv data/post_level_performance.csv

# 4. Run your first analysis
./analyze --period "2024-09-21,2024-09-28" --event "Conference Week" --export-data

🛠 Installation

Automatic Setup

./install.sh

Manual Setup

pip install -r requirements.txt
chmod +x analyze
mkdir -p data output

Dependencies

• Python 3.8+
• pandas >= 2.2.0
• numpy >= 2.0.0
• openai >= 1.54.0 (for AI features)

📖 Usage

Basic Analysis Options

Default Analysis (This week vs last week)

./analyze

Custom Period Analysis

./analyze --period "2024-09-21,2024-09-28" --event "Product Launch"

Year-over-Year Comparison

./analyze --yoy "2024-09-21,2024-09-28" --event "Annual Conference"

Custom Comparison Periods

./analyze --compare "2023-09-22,2023-09-29,2024-09-21,2024-09-28" --event "Campaign Analysis"

Advanced Features

Export Detailed Data

./analyze --period "2024-09-21,2024-09-28" --export-data

AI-Powered Strategic Insights

./analyze --period "2024-09-21,2024-09-28" --event "Q3 Campaign" --ai

Combined Analysis with Full Export

./analyze --compare "2023-09-22,2023-09-29,2024-09-21,2024-09-28" --event "UNGA Week" --export-data --ai

Command-Line Options

Option	Description	Example
--period	Analyze specific period vs equivalent previous period	"2024-09-21,2024-09-28"
--compare	Custom comparison between two specific periods	"2023-09-22,2023-09-29,2024-09-21,2024-09-28"
--yoy	Year-over-year comparison	"2024-09-21,2024-09-28"
--event	Event name for reports	"Product Launch"
--export-data	Include detailed data export in report
--ai	Generate AI-powered strategic insights

📊 Data Requirements

Sprout Social Export Setup

1. Export Type: Post-level performance data
2. Date Range: Include all periods you want to analyze
3. File Location: Save as data/post_level_performance.csv
4. Platforms: Include all platforms you want analyzed

Required CSV Columns

• Date: MM/DD/YYYY HH:MM AM/PM format
• Network: Platform name (Instagram, LinkedIn, YouTube, etc.)
• Content Type: Post type (Video, Photo, Link, etc.)
• Engagements: Total engagement count
• Post: Post text/description

Optional Columns (Enhanced Analysis)

• Video Views, Reach, Impressions
• Likes, Comments, Shares, Saves
• Post Link Clicks, Profile Clicks
• Platform-specific metrics

📈 Output Examples

Analysis Report Structure

📄 event_name_analysis_YYYYMMDD_HHMM.md
├── Executive Summary
├── Platform Performance Table
├── Key Insights & Recommendations
├── Platform-Specific Analysis
├── Content Performance Insights
└── [Optional] Detailed Data Export

Sample Output

# Product Launch Performance Analysis

**Period 1**: 2024-09-15 to 2024-09-22  
**Period 2**: 2024-09-22 to 2024-09-29  
**Generated**: 2024-09-29 14:30:15

## Executive Summary

**Overall Performance**: +42.9% engagement change  
**Platforms Analyzed**: 7  
**Total Posts**: 240 → 285 (+45)

## Platform Performance

| Platform | Period 1 | Period 2 | Change | Avg Engagement |
|----------|----------|----------|---------|----------------|
| Instagram | 5,389 | 6,142 | +14.0% | 120 |
| LinkedIn | 4,967 | 7,757 | +56.2% | 189 |
| TikTok | 2,145 | 3,201 | +49.2% | 267 |

🤖 AI Integration

Setup

export OPENAI_API_KEY="your-api-key-here"

Features

• GPT-5 Reasoning Model: Advanced strategic analysis
• Performance Pattern Recognition: AI identifies optimization opportunities
• Platform-Specific Recommendations: Tailored advice for each platform
• Actionable Insights: Specific next steps and tactical guidance

AI Output Sample

## AI Strategic Insights

### Key Performance Drivers
- Video content showing 3x higher engagement than static posts
- LinkedIn professional content outperforming by 56%
- Optimal posting window identified: 9-11 AM EST

### Optimization Opportunities
1. **Instagram**: Increase Reels production by 40%
2. **LinkedIn**: Focus on thought leadership content
3. **TikTok**: Leverage trending audio for 2x reach improvement

🔍 Platform Analysis

Supported Platforms

Platform	Key Metrics	Specialized Analysis
Instagram	Posts, Reels, Stories, Reach, Saves	Hashtag strategy, content type optimization
LinkedIn	Professional engagement, clicks, shares	B2B content performance, thought leadership
YouTube	Views, watch time, subscribers	Video retention, SEO optimization
TikTok	Video views, shares, For You page	Viral content identification, algorithm insights
X/Twitter	Retweets, replies, link clicks	Real-time engagement, news distribution
Facebook	Reach, reactions, community engagement	Content type performance, audience insights
Threads	Posts, replies, reposts	Community building, conversation metrics

Analysis Depth

Each platform analyzer provides:

• ✅ Performance Metrics: Core engagement and reach statistics
• ✅ Content Insights: Best performing content types and formats
• ✅ Timing Analysis: Optimal posting schedules and frequency
• ✅ Growth Opportunities: Data-driven recommendations for improvement
• ✅ Competitive Positioning: Performance context and benchmarking

🏗 Architecture

Project Structure

sprout-analytics-cli/
├── analyze                    # Main CLI tool
├── modules/                   # Platform analysis modules
│   ├── instagram_analysis.py
│   ├── linkedin_analysis.py
│   ├── tiktok_analysis.py
│   └── youtube_analysis.py
├── data/                     # CSV data files (gitignored)
├── output/                   # Generated reports
├── install.sh               # Setup script
└── requirements.txt         # Python dependencies

Core Components

• Analysis Engine: Data processing and period comparison logic
• Platform Analyzers: Specialized analysis for each social platform
• Report Generation: Professional markdown output with insights
• AI Integration: OpenAI GPT-5 for strategic recommendations

🔒 Privacy & Security

• Local Processing: All data analysis performed locally on your machine
• Data Protection: CSV files automatically excluded from version control
• Optional AI: OpenAI integration only when explicitly requested with --ai
• No Data Retention: Tool processes but doesn't store your organizational data

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/yavzius/sprout-analytics-cli.git
cd sprout-analytics-cli
pip install -r requirements.txt
chmod +x analyze

Running Tests

# Test with sample data
./analyze --period "2024-09-01,2024-09-08" --event "Test Analysis" --export-data

📄 License

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

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

🙏 Acknowledgments

• Built for modern social media management workflows
• Optimized for Sprout Social data exports
• Designed with enterprise analytics needs in mind

---

Professional Sprout Social analytics CLI designed for data-driven content strategy and performance optimization.