🎵 Spotiline

Because graphical interfaces are overrated (-cli nerds)

The headless, native Spotify client engineered for terminal power users and autonomous AI agents.

Installation • Documentation • Contributing

✨ Features

🧑‍💻 Human Mode (TUI)

• 24-bit color dashboard with real-time status
• Keyboard-driven navigation (no mouse needed)
• Live search with instant results
• <50MB RAM idle, <100ms launch time

🤖 Agent Mode (CLI)

• Stateless commands for scripting
• --json flag for clean, machine-readable output
• Perfect for AI agents and shell automation
• Zero-config pipeline integration

🚀 Quick Start

Install

cargo install spotiline

Start the Engine

spotiline daemon start

Launch the UI

spotiline

Or control via CLI:

spotiline play

spotiline status --json

spotiline search "lofi beats" --play

📖 Documentation

Full documentation available at: https://ejafee.github.io/spotiline

Quick Links

• Installation Guide
• CLI Command Reference
• TUI Keyboard Bindings
• AI & JSON Outputs

⚠️ Requirements

• Spotify Premium account (required for playback control via Spotify Web API)
• Active internet connection
• At least one active Spotify device (official app or speaker)

🏗️ Architecture

spotiline binary
    ├─ TUI (ratatui)          # Terminal dashboard
    └─ CLI (clap)             # Command interface
         ↓
    TCP IPC (127.0.0.1:47836)
         ↓
    Background Daemon
         └─ Spotify Web API (rspotify)

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Roadmap (v1.1+)

• Synced lyrics integration (lrclib.net)
• Podcast support
• Real-time FFT audio visualizer
• Playlist management

📝 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

• rspotify - Spotify Web API client
• ratatui - Terminal UI framework
• clap - CLI argument parser

Made with ❤️ for the terminal