cue

✓ Stable v1.0.0

Unified command-line Spotify controller with timed sessions

Control Spotify playback through intelligent queuing, contextual listening modes, and timed sessions. Features automatic background server and history tracking.

GitHub Get Started

Quick Start

cue provides smart Spotify control from the command line with timed sessions, automatic background server, and pre-configured listening modes.

Basic Usage

$cue play "Bohemian Rhapsody"

Playing: Bohemian Rhapsody - Queen Duration: full track (5:55) Session ends: --

$cue play "jazz piano" 30m

Playing: Jazz Piano Trio - Various Duration: 30 minutes Session ends: 14:45

$cue focus

Starting focus mode (2h) Playing: Lo-Fi Beats - Instrumental Energy: low, Tempo: moderate

Installation

From PyPI

pip

$pip install cue

Successfully installed cue-1.0.0

$cue --version

cue 1.0.0

From Source

Source

$git clone https://github.com/tenseleyFlow/cue.git

$cd cue && pip install -e .

From RPM

DNF

$sudo dnf install cue

Spotify Setup

cue requires Spotify Premium and API credentials:

Go to Spotify Developer Dashboard
Create a new application
Add http://localhost:8080/callback to Redirect URIs
Copy your Client ID and Client Secret
Set environment variables:

Environment

$export SPOTIFY_CLIENT_ID='your_client_id'

$export SPOTIFY_CLIENT_SECRET='your_client_secret'

$cue health

Server: running Spotify: authenticated Device: Desktop - active

First Run

On first use, cue opens a browser for Spotify authorization:

Authorization

$cue status

Opening browser for Spotify authorization... Waiting for callback... Authorization successful! No active playback

$cue play "your favorite song"

Playing: Your Favorite Song - Artist Duration: full track

Dependencies

Requirements

Python 3.8+
Spotify Premium - Required for playback control
click, requests, flask, spotipy

Configuration

cue is configured through environment variables and config files in ~/.cue/.

Environment Variables

Option	Type	Default	Description
`SPOTIFY_CLIENT_ID`	string	(required)	Spotify API client ID from developer dashboard
`SPOTIFY_CLIENT_SECRET`	string	(required)	Spotify API client secret
`SPOTIFY_REDIRECT_URI`	URL	http://localhost:8080/callback	OAuth redirect URI
`CUE_SERVER_HOST`	string	0.0.0.0	Server bind address
`CUE_SERVER_PORT`	integer	8080	Server port
`CUE_CLIENT_SERVER_URL`	URL	http://localhost:8080	Target server URL
`CUE_CLIENT_TIMEOUT`	seconds	30	Request timeout
`CUE_NO_AUTO_SERVER`	boolean	false	Disable auto-server startup

Server Configuration

Background server settings:

Option	Type	Default	Description
`host`	string	0.0.0.0	Server bind address
`port`	integer	8080	Server listen port
`timeout`	seconds	30	Request timeout
`debug`	boolean	false	Enable debug logging

Playback Settings

Option	Type	Default	Description
`default_duration`	string	full	Default playback duration
`max_search_results`	integer	50	Maximum search results
`queue_position_limit`	integer	100	Maximum queue size
`token_refresh_buffer`	seconds	600	Refresh token 10 min early

Config Files

~/.cue/client.json - Client configuration (server_url, timeout)
~/.cue/modes.json - Custom mode definitions
~/.cue/cue.db - SQLite database for sessions and queue
~/.cue/server.pid - Server process ID
~/.cue/server.log - Server output log

Client Config

Client Settings

$cue config

server_url: http://localhost:8080 timeout: 30

$cue config --url http://server:8080

$cue config --timeout 60

Overview

cue is a unified command-line Spotify controller that enables smart playback management through timed sessions, intelligent queuing, and contextual listening modes.

Key Features

Timed playback sessions with automatic pause
Pre-configured listening modes (focus, party, workout, etc.)
Automatic background server for remote control
Queue management with auto-advance
Volume and device control
Playback history tracking

System Overview

cue uses a client-server architecture where the CLI communicates with a background Flask server that manages Spotify state.

cue/
├── __init__.py           # Package metadata
├── __main__.py           # Module entry point
├── main.py               # Smart dispatcher
├── cli/
│   ├── commands.py       # Click CLI definitions
│   └── client.py         # HTTP client
├── core/
│   ├── config.py         # Configuration
│   ├── spotify.py        # Spotify API wrapper
│   ├── database.py       # SQLite storage
│   ├── models.py         # Data models
│   ├── duration.py       # Duration parsing
│   └── formatting.py     # Display formatting
└── server/
    ├── app.py            # Flask application
    ├── handlers.py       # Request handlers
    ├── session.py        # Session manager
    ├── modes.py          # Mode definitions
    └── queue.py          # Queue processing

CLI Reference

Complete command-line interface reference for cue.

Playback Commands

Option	Type	Default	Description
`cue play <query> [duration]`	command	-	Play track with optional duration
`cue play album <name> [duration]`	command	-	Play an album
`cue play artist <name> [duration]`	command	-	Play artist top tracks
`cue play playlist <name> [duration]`	command	-	Play a playlist
`cue play genre <name> [duration]`	command	-	Play genre-based recommendations
`cue stop`	command	-	Stop current playback
`cue skip`	command	-	Skip to next track
`cue status`	command	-	Show playback status

Queue Commands

Option	Type	Default	Description
`cue queue add <query> [duration]`	command	-	Add track to queue
`cue queue list`	command	-	Show queued items
`cue queue clear`	command	-	Clear all queue items

Mode Commands

Option	Type	Default	Description
`cue focus [duration]`	command	2h	Focus mode - low energy, instrumental
`cue party [duration]`	command	3h	Party mode - high energy, danceable
`cue workout [duration]`	command	1h	Workout mode - high BPM, energetic
`cue sleep [duration]`	command	45m	Sleep mode - minimal energy, slow tempo
`cue morning [duration]`	command	30m	Morning mode - positive vibes
`cue chill [duration]`	command	1h	Chill mode - relaxed
`cue mode list`	command	-	List all modes
`cue mode start <name> [duration]`	command	-	Start specific mode
`cue mode stop`	command	-	Stop current mode

Volume Commands

Option	Type	Default	Description
`cue volume set <0-100>`	command	-	Set volume level
`cue volume get`	command	-	Get current volume
`cue vol <0-100>`	command	-	Quick volume set
`cue louder [amount]`	command	+10	Increase volume
`cue quieter [amount]`	command	-10	Decrease volume
`cue mute`	command	-	Mute (set volume 0)

Device Commands

Option	Type	Default	Description
`cue device list`	command	-	List available devices
`cue device switch <name>`	command	-	Switch to device

Server Commands

Option	Type	Default	Description
`cue health`	command	-	Check server and Spotify connection
`cue --server`	command	-	Start server mode
`cue --server-stop`	command	-	Stop background server
`cue --server-status`	command	-	Check server status
`cue --server-logs`	command	-	View server logs

History Commands

Option	Type	Default	Description
`cue history`	command	-	Show playback history
`cue history -n <num>`	command	20	Limit history items
`cue history --today`	command	-	Today only
`cue history --this-week`	command	-	This week only
`cue history -c`	command	-	Include Spotify history

Usage Examples

Common Workflows

$cue focus 2h

Start 2-hour focus session

$cue status

Playing: Lo-Fi Study Beats Time remaining: 1h 45m

$cue quieter 20

Volume: 60 → 40

$cue skip

Skipped to next track

$cue stop

Playback stopped

Troubleshooting

Common issues and solutions when using cue.

Spotify credentials not found

Problem: Error about missing credentials.

Solution: Set environment variables:

Fix

$export SPOTIFY_CLIENT_ID='your_id'

$export SPOTIFY_CLIENT_SECRET='your_secret'

Spotify not authenticated

Problem: First run fails authentication.

Solution: Run any command and complete browser OAuth flow. Ensure http://localhost:8080/callback is in your Spotify app's redirect URIs.

No devices available

Problem: Can't play - no active devices.

Solution:

Open Spotify on any device (phone, desktop, web)
Start playing something briefly to wake the device
Run cue device list to verify

Server connection issues

Problem: Commands fail with connection errors.

Solution: Check server status:

Debug

$cue health

Check overall health

$cue --server-status

Check server running

$cue --server-logs

View error logs

$cue --server-stop && cue --server

Restart server

Track not found

Problem: Search returns no results.

Solutions:

Try including artist name: "Song Name Artist"
Check spelling and try variations
Verify track is available in your region

Queue not advancing

Problem: Queue items don't play automatically.

Solution:

Check cue status for active session
Verify queue: cue queue list
Check server logs: cue --server-logs

Premium required error

Problem: Playback control fails.

Cause: Spotify Premium is required for playback control API. Free accounts can only read playback state, not control it.

Disable Auto-Server

If you prefer to manage the server manually:

Manual Server

$export CUE_NO_AUTO_SERVER=1

$cue --server &

Start server manually

$cue play "song"

Now uses existing server

$cue --server-stop

Stop when done

Getting Help

GitHub Issues: Report bugs or request features
Built-in Help: cue --help
Command Help: cue play --help

cue

Quick Start

Installation

From PyPI

From Source

From RPM

Spotify Setup

First Run

Dependencies

Requirements

Configuration

Environment Variables

Server Configuration

Playback Settings

Config Files

Client Config

Overview

Key Features

Authentication

OAuth Flow

Required Scopes

Token Management

Playback Control

Timed Sessions

Duration Format

Queue System

Listening Modes

focus (2h default)

party (3h default)

workout (1h default)

sleep (45m default)

morning (30m default)

chill (1h default)

Device Control

System Overview

Module Structure

CLI Layer

Components

Core Services

Components

Server Layer

Components

Data Flow

Database Schema

CLI Reference

Playback Commands

Queue Commands

Mode Commands

Volume Commands

Device Commands

Server Commands

History Commands

Usage Examples

Troubleshooting

Spotify credentials not found

Spotify not authenticated

No devices available

Server connection issues

Track not found

Queue not advancing

Premium required error

Disable Auto-Server

Getting Help