Installation
Download
Download the right version for your Mac:
Not sure which? Click the Apple menu → About This Mac. If it says Apple M1/M2/M3/M4, choose Apple Silicon. Otherwise choose Intel.
Install
Open the downloaded .dmg file. Drag StackStats into the Applications folder.
Open the app
Go to Finder → Applications and double-click StackStats. macOS will block it and show an error dialog — that’s expected. Click Done to dismiss it.
Allow in System Settings
Open System Settings → Privacy & Security and scroll down. You’ll see a message saying “StackStats was blocked.” Click Open Anyway.
Confirm & launch
macOS will ask you to confirm one more time — click Open. Enter your Mac password or use Touch ID if prompted. StackStats will launch.
macOS blocks apps from developers who don’t have an Apple Developer certificate ($99/year). I’ve applied for one and this warning will go away once it’s issued. StackStats is not malware — it’s a local app that never sends your data anywhere. Sorry for the inconvenience.
Download
Run the installer
Double-click StackStats-Setup.exe. If Windows SmartScreen appears, click More info and then Run anyway.
Complete installation
The installer will complete and launch StackStats automatically.
Windows flags apps that aren’t code-signed. I’m in the process of getting a Windows certificate and this warning will disappear once that’s done. StackStats runs entirely on your machine and never sends your subscriber data anywhere. Sorry for the inconvenience.
Getting Started
Enter your license key
When StackStats opens for the first time, it will show a license screen. Check your Gumroad purchase email for your key — paste it in and click Activate.
Option A — Auto-Sync (Beta)
Auto-Sync downloads all your Substack data files directly from within the app. No manual exporting needed, but requires an internet connection.
On first use you’ll be prompted to log in to Substack — this is a one-time step.
- Open StackStats → click Settings in the topbar
- Find the Auto-Sync section at the top
- Enter your Substack publication URL (e.g.
yourname.substack.com) → click Connect - Click Sync Now — all files download automatically in 3–4 minutes
Files downloaded: traffic, followers, growth sources, audience location (countries + US states), email stats, traffic sources, subscriber export, and ZIP export (9 files total).
Option B — Manual Download
Download export files from your Substack dashboard and load them directly into the app. Works offline — no login required.
Download your data files
-
Substack ZIP export — the most valuable file. Unlocks per-post open rates, click rates, device breakdown, and geographic data.
Substack dashboard → Settings → Export data → click New Export → wait for the email → download the.zipfileIf your Mac automatically extracts the ZIP into a folder, that’s fine — StackStats handles both.
-
Subscribers — full subscriber list with engagement history, country, and activity data.
Dashboard → Audience → click the 3 dots (⋯) at top right of the table → Export all columns → ExportMake sure to choose Export all columns — this gives you 43 fields including engagement, activity, and location data.
-
Growth sources — daily new subscribers and visitors broken down by traffic source.
Dashboard → Growth → set period to All time → 3 dots (⋯) → Download CSV
-
Audience location & followers — signup counts by country, US state/province, and follower growth. All from the same page — 3 downloads.
Dashboard → Stats → Audience tab → set period to All time- Set location to World, All subscribers → 3 dots → Download CSV (countries file)
- Set location to USA, All subscribers → 3 dots → Download CSV (US states file)
- Switch metric to Followers → 3 dots → Download CSV (followers file)
-
Traffic (page views) — daily page views for your publication.
Dashboard → Stats → Traffic → Total Traffic table → choose your date range → 3 dots (⋯) → Download CSV
-
Traffic sources — which sites and search terms are sending you readers.
Dashboard → Stats → Traffic → scroll down to the Traffic by source table → 3 dots (⋯) → Download CSV
Load your data into StackStats
Once you have the files downloaded, open the app and click Settings in the topbar.
In the Manual Upload section, set your auto-scan folder to wherever you saved the downloads, then click Scan Now. StackStats will detect and import all matching files automatically.
If a file wasn’t picked up automatically, use the Browse button next to that file type to add it manually.
AI Insights
AI insights are totally optional and need to be configured only if you want a deep analysis with an LLM. StackStats works completely without AI except the AI insights tab. The AI Insights tab generates four insight cards (Growth, Engagement, Audience, 30-Day Plan) and gives you a live chat interface to ask questions about your newsletter data.
StackStats supports multiple AI providers and works on bring your own key model(BYOK). You choose a provider of your choice and configure it yourself as per your liking. Your data is never sent raw — only aggregated summaries are shared with the AI.
Connecting a provider
Open Settings → scroll to the AI Provider section. Select your provider from the dropdown, enter your API key, and click Test Connection.
Supported providers
| Provider | Model | Notes |
|---|---|---|
| Anthropic | Claude (Sonnet, Haiku, Opus) | Recommended. Get key at console.anthropic.com |
| OpenAI | GPT-4o, GPT-4o mini | Get key at platform.openai.com |
| Google Gemini | Gemini 1.5 Flash, Pro | Get key at aistudio.google.com |
| OpenRouter | Any model on OpenRouter | Single API key for many models |
| Groq | Llama 3, Mixtral, Gemma | Fast inference, free tier available |
| Ollama | Any local model | Runs entirely on your machine — no API key needed |
| Custom | Any OpenAI-compatible endpoint | Set a custom base URL for self-hosted models |
Generating insights
Once connected, go to the AI Insights tab and click Generate Insights. The four cards will populate with analysis specific to your newsletter data.
Use the chat panel on the right to ask follow-up questions — for example, “Which post drove the most new subscribers?” or “What day of the week gets the best open rates?”
Auto-Updates
StackStats checks for updates automatically every time you launch the app.
If a new version is available, you’ll see an update prompt on the startup screen before the app fully loads. Click Update Now to download and install — the app will restart automatically when done.
You can also check manually: open Settings → scroll to the About section → click Check for updates.
Updates are delivered over-the-air from GitHub Releases. The download typically takes 30–60 seconds depending on your connection. You don’t need to reinstall or visit any website.
Troubleshooting
A file isn’t being detected. StackStats classifies files by their column headers, not filename. Make sure the file hasn’t been modified after downloading. Try adding it manually via the Browse button in Settings.
Auto-Sync fails or gets stuck. Check your internet connection and make sure the Substack URL is entered without https:// (e.g. yourname.substack.com). If it keeps failing, use Manual Download instead.
The app shows no data after loading files. Open Settings and check that files show green checkmarks under Your Data. If a file shows a warning, it may be empty or in an unexpected format — try re-downloading it from Substack.
Charts are blank on a tab. Some charts require specific file types. The Deep Dive tab needs the subscriber export; the Publications tab needs the ZIP export or email stats. Check the empty-state message on the tab for a hint.
macOS blocks the app after an update. Gatekeeper sometimes resets after an OTA update. Go to System Settings → Privacy & Security and click Open Anyway again.
AI insights won’t generate. Make sure your API key is saved and the connection test passes (green tick in Settings). If you’re using Ollama, confirm it’s running locally (ollama serve in terminal).
StackStats is improving every day. If you run into anything not listed here, reach out at [email protected] or find me as rishikeshs on Discord. Fixes ship via over-the-air updates automatically.
← Back to StackStats