Statify

Terminal + local web utility for your Spotify listening stats.

Sync plays to a local SQLite database, explore tops and genres in a TUI or browser UI, and import Extended Streaming History for longer-term totals.

Requirements

• OS: macOS, Linux, or WSL (Unix)
• Python: 3.12+
• Spotify (import-only): any account — download Extended Streaming History from Account Privacy and run statify import (no Client ID, no Premium)
• Spotify (live sync / API): Premium + a Dev Mode app Client ID (no Client Secret) for statify login and statify sync

What you get

• CLI — sync, tops, recent, library, playlists, genres, stats, gaps
• TUI — interactive terminal dashboard (statify tui)
• Local web UI — browser dashboard on 127.0.0.1 (statify web)
• History import — GDPR / Extended Streaming History ZIP

Screenshots

---

Quick install (recommended)

curl -fsSL https://raw.githubusercontent.com/parthUltra/statify/main/install.sh | bash

Or clone and run the installer:

git clone https://github.com/parthUltra/statify.git
cd statify
./install.sh

This installs into ~/.local/share/statify/ and puts a statify launcher on your PATH (~/.local/bin).

Then either:

# Import-only (no Premium / Client ID)
statify import   # or: statify import ~/Downloads/my_spotify_data.zip
statify stats    # or: statify tui / statify web

# Live API sync (Premium + Client ID)
statify setup    # guided Client ID setup — prompts and saves locally
statify login    # browser login (PKCE)
statify sync
statify tui      # or: statify top tracks / statify web

Update to the latest version

statify update

That’s the only command you need going forward. It resets your managed install to the latest main on GitHub. Code updates apply instantly (editable install); pip only runs again when dependencies in pyproject.toml change. Use statify update --reinstall to force a full dependency refresh.

---

Get a Spotify Client ID

Skip this section if you only plan to import a privacy export ZIP.

Spotify calls this a Client ID (not an “API key”). Live API access in Dev Mode requires a Premium account for the app owner (2026).

1. Open developer.spotify.com/dashboard and log in
2. Create app
   • Name: Statify
   • Redirect URI: http://127.0.0.1:8765/callback ← must match exactly
   • Check Web API
3. Open the app → Settings → copy Client ID
4. Under User Management, add yourself if the dashboard asks

No Client Secret is required (Statify uses PKCE).

Save it from the terminal

statify setup

The wizard prints these steps, can open the dashboard, then prompts:

Paste your Spotify Client ID: ********************************

It saves to your user config file (permissions 600), e.g.:

OS	Settings file
Linux	~/.config/statify/settings.json
macOS	~/Library/Application Support/statify/settings.json

See paths anytime with:

statify config

You can also set SPOTIFY_CLIENT_ID in the environment or a .env file; env wins over the saved file.

If you run statify login before setup, it will offer the same prompt automatically.

---

Manual install (pip / venv)

git clone https://github.com/parthUltra/statify.git
cd statify
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
statify setup
statify login

Requires Python 3.12+.

---

Everyday commands

statify setup                 # save / replace Client ID
statify config                # show config + data paths
statify update                # pull latest from GitHub + reinstall
statify login                 # authorize Spotify
statify logout
statify sync                  # pull recent plays + now playing + tops
statify import                # guided GDPR / Extended History import
statify import PATH           # import a ZIP or JSON path
# (alias: statify import-history …)

statify top tracks [-n 20] [-t short|medium|long]
statify top artists
statify top tracks --history  # local play counts
statify recent
statify now
statify library
statify playlists
statify genres
statify stats
statify gaps

statify tui                   # interactive terminal dashboard
statify web                   # local web UI

TUI keys

Key	Action
← / →	Switch screens
/	Command palette
r	Refresh
s	Sync
q	Quit

---

Spotify API limits

Available	Not available
Top artists/tracks (affinity)	Full server-side play history
Recently played (~50)	Audio features / BPM / mood
Now playing, library, playlists	Recommendations
Artist genres	Editorial playlist contents

Wrapped-style totals come from statify sync over time and/or statify import (Spotify privacy download).

---

Import listening history

Spotify’s API cannot give lifetime plays. Request Extended streaming history from any Spotify account — Premium and a Client ID are not required for this path.

statify import

Opens Account Privacy, walks you through the request, then imports a ZIP from Downloads (no unzip needed).

Or once you have the file:

statify import ~/Downloads/my_spotify_data.zip

Then explore with statify stats, statify recent, statify top tracks --history, statify tui, or statify web.

Web UI: Import (or /import) → Open Spotify Account Privacy → upload the ZIP. You’re redirected to Listening after import.

---

Troubleshooting

Problem	What to try
statify: command not found	Ensure ~/.local/bin is on your PATH (restart the shell, or add it in .zshrc / .bashrc). Re-run the installer if needed.
Login / redirect fails	Redirect URI must be exactly http://127.0.0.1:8765/callback in the Spotify app settings.
API / Dev Mode errors	Live sync needs a Dev Mode app whose owner has Premium. Confirm Premium, redirect URI, and that you are listed under User Management. Import-only does not need this.
Stale install	Run statify update (or statify update --reinstall).

---

Support

• Report a bug
• Request a feature
• Security issues: see SECURITY.md (do not open a public issue)

Uninstall

rm -rf ~/.local/share/statify ~/.local/bin/statify
# also remove config/tokens if desired:
# Linux:  rm -rf ~/.config/statify
# macOS:  rm -rf ~/Library/Application\ Support/statify

---

Development

See CONTRIBUTING.md.

pip install -e ".[dev]"
pytest

Changelog

See CHANGELOG.md.

License

MIT