spotnik

command module
v0.1.0-rc3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2026 License: MIT Imports: 1 Imported by: 0

README

CI Latest Release Go Version

Spotnik

A terminal client for Spotify.

Spotnik controls playback on your Spotify Connect devices. It does not play audio itself.

Spotify Premium is required for playback control. See the Spotify Web API docs.

Spotnik screenshot

Install

macOS and Linux

Latest stable release:

curl -fsSL https://raw.githubusercontent.com/initgrep-apps/spotnik/main/install.sh | bash

Pin a specific version:

curl -fsSL https://raw.githubusercontent.com/initgrep-apps/spotnik/main/install.sh | SPOTNIK_VERSION=v0.1.0 bash

After install, open a new terminal — or run . ~/.config/spotnik/env to use spotnik immediately in the current shell.

Windows

Latest stable release:

irm https://raw.githubusercontent.com/initgrep-apps/spotnik/main/install.ps1 | iex

Pin a specific version:

$env:SPOTNIK_VERSION="v0.1.0"; irm https://raw.githubusercontent.com/initgrep-apps/spotnik/main/install.ps1 | iex

The installer updates your user PATH and current PowerShell session.

Other

DEB and RPM packages, plus pre-built binaries, are on the Releases page. You can also install from source:

go install github.com/initgrep-apps/spotnik@latest

Uninstall

The uninstaller wipes tokens from the OS keychain (via spotnik auth forget), removes the binary, removes the env file at ~/.config/spotnik/env plus any installer-managed lines from ~/.bashrc, ~/.zshrc, ~/.bash_profile, ~/.profile, and ~/.config/fish/conf.d/spotnik.fish, and prompts before deleting ~/.config/spotnik.

macOS and Linux
curl -fsSL https://raw.githubusercontent.com/initgrep-apps/spotnik/main/uninstall.sh | bash

Skip the prompt — also delete config:

SPOTNIK_PURGE_CONFIG=1 curl -fsSL https://raw.githubusercontent.com/initgrep-apps/spotnik/main/uninstall.sh | bash

Skip the prompt — keep config:

SPOTNIK_KEEP_CONFIG=1 curl -fsSL https://raw.githubusercontent.com/initgrep-apps/spotnik/main/uninstall.sh | bash
Windows
irm https://raw.githubusercontent.com/initgrep-apps/spotnik/main/uninstall.ps1 | iex
Manual
spotnik auth forget                              # wipe keychain + client ID
sudo rm "$(command -v spotnik)"                  # remove binary
rm -f ~/.config/spotnik/env                      # remove env file
rm -rf ~/.config/spotnik                         # remove config (optional)
# Strip the marker block from any rc files manually if needed.

Setup

Spotify Premium is required (the Web API only allows playback control on Premium accounts).

A Spotify Developer app is needed for the PKCE OAuth flow:

  1. Visit developer.spotify.com/dashboard and create an app.
  2. Add http://127.0.0.1:8888/callback as a redirect URI.
  3. Run spotnik. It bootstraps ~/.config/spotnik/config.toml and prompts for the Client ID.
  4. Your browser opens for authorization. Tokens land in the OS keychain.

Spotnik requests 14 Spotify OAuth scopes. See docs/SCOPES.md for the full list and revocation steps.

Features

Spotnik organises the TUI into two pages with a btop-style, pane-based layout. Page A holds the everyday Spotify panes; Page B is a live developer view of the API gateway.

How to use
  • Press 0 to switch between Page A and Page B.
  • Press 1 through 8 to toggle individual panes. Each pane title shows a small superscript number indicating its toggle key.
  • Press Tab (or Shift+Tab) to move focus between visible panes.
  • Use ↑/↓ (or j/k, or the mouse wheel) to scroll list panes.
  • Press Enter in a list pane to play the highlighted item.
  • Press f to filter a list pane, and Esc to close any overlay or clear a filter.
  • Playback keys (Space, ←, →, +, -, s, r, v) work from any pane.

See Keybindings for the full reference.

Page A: Spotify
  • Now Playing: current track, braille visualizer, gradient seek bar, and volume bar.
  • Queue: upcoming tracks.
  • Playlists: your saved playlists.
  • Albums: your saved albums.
  • Liked Songs: your liked tracks.
  • Recently Played: listening history.
  • Top Tracks: your top tracks.
  • Top Artists: your top artists.
Overlays and global
  • Search: full-screen search across tracks, artists, albums, and playlists, with prefix autocomplete and paginated results.
  • Devices: transfer playback to any Spotify Connect device.
  • Profile: user profile, logout, and forget.
  • Themes: 11 built-in themes with a runtime switcher.
  • Transport: play, pause, skip, shuffle, repeat, and volume. Always active.
  • Layouts: preset cycling (p) and per-pane visibility toggles (1–8).
  • Filter: universal filter on list panes (f, Esc clears).
CLI
  • Auth: spotnik auth {register, login, logout, forget, status}.
  • PKCE OAuth: no client secret required. Tokens are stored in the OS keychain.
Page B: Developer

Live observability for the underlying API gateway.

  • Gateway Health: token bucket, backoff, and rate-limit state.
  • Polling Traffic: per-pane request volume.
  • Live Request Flow: in-flight requests.
  • Network Log: recent API events.

The gateway itself handles rate limiting, request dedup, adaptive polling, and automatic retry-after.

Keybindings

Global
Key Action
/ Search overlay
d Device switcher
u User profile overlay
t Theme switcher
? Help overlay
q Quit
0 Toggle Page A / Page B
1–8 Toggle pane visibility (Page A)
1–5 Toggle pane visibility (Page B)
p Cycle preset layout
Playback (always active)
Key Action
Space Play / pause
← / → Previous / next
+ / - Volume
s Toggle shuffle
r Cycle repeat
v Cycle visualizer pattern
Navigation
Key Action
Tab / Shift+Tab Cycle focus
↑ ↓ j k Scroll
Mouse wheel Scroll the pane under the cursor
Esc Close overlay, clear filter, or scroll to top
Pane actions
Key Action Context
Enter Select or play Focused pane
f Toggle filter List panes
g Cycle time range TopTracks, TopArtists
A Add to queue Search, list panes
Profile overlay
Key Action
l Logout. Press twice to confirm. Keeps the Client ID.
f Forget. Press twice to confirm. Also removes the Client ID.
Search overlay
Key Action
Tab / Shift+Tab Cycle category
Enter Play result
Ctrl+A Add to queue
Ctrl+U Clear input
PgDn / PgUp Page results
Esc Close

Configuration

Spotnik bootstraps ~/.config/spotnik/config.toml on first launch. Full schema with defaults:

# Spotnik configuration
# https://github.com/initgrep-apps/spotnik

[spotify]
# To use your own Spotify app credentials, uncomment and set:
# client_id = "your-client-id-from-spotify-developer-dashboard"

[preferences]
theme = "black"
# preset = 0          # Page A layout preset index (0-based)
# visualizer = 0      # Visualizer pattern index (0-6)

[cli]
# CLI palette: "auto" (default), "fixed", or "theme"
# - auto:  theme colours on dark-bg terminals, fixed elsewhere
# - fixed: always the built-in Spotnik palette
# - theme: inherit the TUI theme (may be unreadable on light terminals)
palette = "auto"

[ui]
# Glyph rendering mode: "auto" (default), "unicode", or "ascii"
# - auto:    use unicode glyphs when LC_ALL/LANG contains UTF-8, else ASCII
# - unicode: always use unicode glyphs (requires a UTF-8 capable terminal)
# - ascii:   always use ASCII fallback glyphs (safe for all terminals)
glyphs = "auto"

Available themes: black (default), monokai, catppuccin, nord, light, dracula, gruvbox, rosepine, solarized, synthwave, tokyonight.

Development

Requires Go 1.26+ and golangci-lint.

git clone https://github.com/initgrep-apps/spotnik.git
cd spotnik
make ci          # fmt-check, tidy-check, lint, test-coverage (>=80%), build
make run         # build and run

Other targets: build, test, test-integration, test-coverage, lint, fmt, tidy-check, clean, install, release.

Architecture and system docs live in docs/system/: architecture.md, design.md, tui.md, cli.md, and api-guide.md.

Tech stack
Layer Library
Language Go 1.26+
TUI runtime Bubble Tea
Components Bubbles
Styling Lip Gloss
Tables bubble-table
Overlays bubbletea-overlay
Config BurntSushi/toml
Keychain zalando/go-keyring
CLI spf13/cobra
HTTP Go stdlib net/http
Testing testing + testify
Release GoReleaser + release-please

License

MIT. See LICENSE.

Documentation

Overview

Spotnik — a terminal Spotify client for developers. This file is the entry point only — no logic lives here.

Source Files

View all Source files

Directories

Path Synopsis
Package cmd provides the CLI entry point for Spotnik via Cobra.
 Package cmd provides the CLI entry point for Spotnik via Cobra.
internal
api
Package api provides the Spotify HTTP client, OAuth authentication flow, and token management.
 Package api provides the Spotify HTTP client, OAuth authentication flow, and token management.
api/apitest
app
Package app contains the root Bubble Tea model that wires together all panes, the central store, and the active theme.
 Package app contains the root Bubble Tea model that wires together all panes, the central store, and the active theme.
cliout
Package cliout renders styled CLI output for the spotnik command-line interface.
 Package cliout renders styled CLI output for the spotnik command-line interface.
config
Package config handles loading and providing application configuration.
 Package config handles loading and providing application configuration.
domain
Package domain contains the shared data types for the Spotnik application.
 Package domain contains the shared data types for the Spotnik application.
keychain
Package keychain provides an abstraction for storing and retrieving OAuth tokens.
 Package keychain provides an abstraction for storing and retrieving OAuth tokens.
prefs
Package prefs provides a coalescing preference writer for Spotnik.
 Package prefs provides a coalescing preference writer for Spotnik.
state
Package state — StateReader is a read-only view of the central Store.
 Package state — StateReader is a read-only view of the central Store.
testhelpers
Package testhelpers provides shared test utilities for the Spotnik test suite.
 Package testhelpers provides shared test utilities for the Spotnik test suite.
ui/components
Package components — timeutil.go provides time-formatting utilities used across panes that display timestamps in human-readable relative form.
 Package components — timeutil.go provides time-formatting utilities used across panes that display timestamps in human-readable relative form.
ui/components/viz
Package viz provides the visualizer engine for the NowPlaying pane.
 Package viz provides the visualizer engine for the NowPlaying pane.
ui/layout
Package layout provides the grid-based layout engine for Spotnik's btop-inspired UI.
 Package layout provides the grid-based layout engine for Spotnik's btop-inspired UI.
ui/panes
Package panes — AlbumsPane displays the user's saved albums in a dense table with in-pane filtering.
 Package panes — AlbumsPane displays the user's saved albums in a dense table with in-pane filtering.
ui/theme
This file contains ConfigTheme — the sole concrete implementation of Theme used for all built-in and user-provided themes loaded from TOML files.
 This file contains ConfigTheme — the sole concrete implementation of Theme used for all built-in and user-provided themes loaded from TOML files.
uikit
Package uikit implements the Spotnik TUI design system.
 Package uikit implements the Spotnik TUI design system.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.