Tune CLI - Specification and Documentation

Tune CLI is a professional-grade command-line interface designed for managing Spotify playback within a terminal-centric development workflow. It provides a low-latency interface to the Spotify Web API, optimized for efficiency and minimal system resource consumption.

Technical Foundations

• Runtime: Node.js
• Language: TypeScript
• Architecture: Modular Service-based Pattern
• Authentication: OAuth2 with PKCE (Proof Key for Code Exchange)

Installation Guide

To provision the CLI globally on your system, execute the following command:

npm install -g @rithvik7/devtune

Authentication

Tune CLI utilizes a secure authentication mechanism that does not require the manual provisioning of client secrets.

1. Execute tune login.
2. Authorize the application via the secure browser redirect.
3. The CLI will automatically receive and persist the access and refresh tokens locally.

Command Reference

Playback Execution

• tune play <song...>: Search for and immediately play specific tracks.
• tune pause: Suspend the current playback session.
• tune toggle: Switch between play and pause states.
• tune next: Skip to the succeeding track in the queue.
• tune prev: Return to the preceding track.

State Management

• tune status: Retrieve a detailed report of the current playback state, including track metadata.
• tune volume <0-100>: Adjust the primary output volume of the active device.
• tune devices: List all available and active Spotify-compatible devices.

Queue Management

• tune queue <song...>: Append a track to the existing playback queue.
• tune queue-list: Display the upcoming 10 tracks in the current session.

Environmental Configurations

• tune focus: Activate the pre-configured Deep Work playlist.
• tune hype: Activate the pre-configured High Tempo playlist.

Advanced Configuration

The application persists settings at ~/.tune/config.json.

Custom Environmental Overrides

Users may override the default focus and hype playlists by providing a Spotify Playlist URI:

tune config set focus spotify:playlist:<playlist-id>
tune config set hype spotify:playlist:<playlist-id>

Custom Client Integration

To use isolated rate-limiting or private developer credentials:

tune config set clientId <your-client-id>

Security Compliance

• PKCE Implementation: Ensures secure code exchange without exposing a client secret.
• Local Persistence: Sensitive data is stored exclusively on the user's filesystem.
• Credential Safety: Authentication occurs via official Spotify accounts; passwords are never visible to the application.

Keywords: spotify, cli, terminal, music, playback, developer-tools, workflow, productivity, typescript

License: MIT Author: Rithvik Shetty