Modern TUI control panel for Spicetify + Spotify Desktop
_{v2.4.0 — Professional PowerShell architecture with arrow-key navigation}

---

What's New in v2.4.0

• Marketplace catalog in the TUI — Browse the top-starred Marketplace extensions online (same discovery as the Spotify sidebar app: GitHub spicetify-extensions topic + manifest.json), download, enable and apply without leaving the manager. Community-code warning before every install
• Community themes browser — One-click install from the official spicetify/spicetify-themes collection (color.ini + user.css + theme.js, then current_theme + apply)
• Color schemes — Pick [Scheme] variants from your active theme's color.ini (spicetify config color_scheme)
• Missing CLI commands covered — refresh (with scope: all/theme/extensions/apps/config), restart, clear, dev watch mode, and inject_css / replace_colors toggles in Advanced
• Marketplace status — Status screen shows marketplace files/enabled badges plus active theme + scheme; Themes menu has a status/enable entry and a 5-item offline built-in extensions picker
• Limitation (by design) — CSS snippets live in Marketplace localStorage and can't be managed from the CLI; browse/install them inside Spotify's Marketplace sidebar

What's New in v2.3.0

• Grouped main menu (lazygit/k9s style) — The 14 flat options are now 4 visual sections (Spicetify / Spotify / Customize / Info & Settings) with non-selectable ─ Section ─ dividers; arrow navigation skips headers automatically and number keys map to the n-th selectable item
• Keybinding hint bar — Compact contextual footer under every menu: ↑↓ navigate · Enter select · Esc back · 1-9 jump
• Semantic status badges — Show-Status now renders [ OK ] green / [WARN] amber / [MISS] red per component (Flipt DESIGN.md color semantics) instead of plain YES/NO
• Success screens with next steps — Auto Apply, Quick Repair and Full Restore end with a summary box plus actionable follow-ups (e.g. press Ctrl+Shift+R if themes look stale)
• Fixed — Crash (Controlador no válido) when running on redirected/invalid consoles: Clear-Host is now wrapped in a safe Clear-Console helper
• Fixed (root cause of the v2.2.x "missing/shifted options" saga) — Initialize-ConsoleSize no longer grows the console in pty terminals (Windows Terminal): conpty granted viewports taller than the physical window, so every row address the menu computed pointed at invisible buffer rows. In WT the app now uses the true viewport and the arrow-menu frame auto-selects the 8-row compact banner (fit-check); legacy conhost keeps the 50-row grow, and consoles too short for even the compact frame fall back to the numbered menu

What's New in v2.2.6

• Flicker-free menu repaint (Istar-Pack style) — Each arrow press now repaints only the two rows that changed (old + new selection) instead of redrawing the whole frame, so navigation no longer flashes. Row addresses are computed arithmetically from a single stable cursor read (no post-draw CursorTop reads, which go stale on Windows Terminal — microsoft/terminal #8312). Also removed an accidental double initial draw

What's New in v2.2.5

• Zero-addressing menu redraw — Fixes duplicated/shifted rows after the first arrow press on Windows Terminal: every frame is now fully sequential (no cursor reads, no cursor moves at all in the menu path). Root cause was stale [Console]::CursorTop reads (microsoft/terminal #8312). If your banner shows v2.2.4 or older, re-download the script — same number, older code

What's New in v2.2.4

• Robust menu repaint — Fixes options randomly missing/duplicated on Windows Terminal: the initial paint is now strictly sequential (zero cursor moves, immune to conpty cursor-tracking bugs), keypress repaints use verified cursor moves with retry (Set-ConsoleCursorPosition), and repaint rows are derived from the final cursor position (Get-MenuTopFromHint), immune to scrolling during the draw (see microsoft/terminal #8312, #17270). Verified visually: 14/14 options in conhost + Windows Terminal, keyboard cycle test passes

What's New in v2.2.3

• Classic block banner restored — The SPICETIFY logo is back to the original █ block art (use Cascadia Code/Mono or Consolas; raster fonts can't render U+2588)

What's New in v2.2.2

• Font-safe ASCII banner — The SPICETIFY logo now uses # block letters (pure ASCII) instead of █ block elements, fixing garbled output on consoles whose font lacks U+2588
• Bug fixes — Self-update parses the real Version : x.y.z header, -Silent no longer hangs on key prompts, single-file injection detection, YAML+INI config parsing, .bat forwards args (%*), -SpicetifyArgs/-ProfileName renames

---

What's New in v2.2.0

• Arrow-key navigation — Main menu uses up/down arrows with ► bullet marker (Istar-Pack style)
• Box-drawing separators — Banner now uses ─ instead of = (matches Istar-Pack)
• In-place repaint — Menus repaint without flicker using cursor positioning
• Fallback mode — Non-interactive consoles use numeric input automatically

What's New in v2.1.0

• Persistent JSON settings — Configuration saved to $HOME/.spicetify-manager/settings.json
• Silent mode — Run non-interactively with -Silent parameter
• Advanced UI helpers — Progress bars, spinners, arrow-key menus
• About screen — App info, version, license, and links
• Enhanced parameters — -ShowProgress, -EnableDebug, -AutoFix, -AutoOpen, -NoPersist
• Console size initialization — Adaptive terminal sizing

What's New in v2.0.0

• Modern curved borders (╭─╮ style instead of ┌─┐)
• Enhanced color palette — Magenta logo, Cyan highlights for better accessibility
• L2 UTF-8 box-drawing — Professional terminal UI
• Info helper for neutral informational messages
• Adaptive window width for better terminal compatibility

---

Features

Feature	Description
Auto Apply	One-command spicetify auto — backup, apply, and launch Spotify
Full Restore	Restore, backup, and re-apply in a single guided flow
Quick Repair	Fast backup apply when things break after a Spotify update
Theme Manager	List, apply, and switch themes by name
Color Schemes	Pick scheme variants from the active theme's color.ini
Online Extensions	Browse/search the Marketplace catalog (GitHub) and install in one flow
Community Themes	One-click install from the official spicetify-themes collection
Built-in Extensions	Offline picker for the 5 extensions that ship with Spicetify
Marketplace Status	Detect files + enabled state, one-click enable of the sidebar app
Extensions	Enable and manage Spicetify extensions
Marketplace	Install or repair the Spicetify Marketplace
Spotify Desktop	Detect Store vs Desktop, auto-install the correct version
Path Repair	Automatically fix spotify_path and prefs_path in spicetify config
Upgrade	One-click Spicetify CLI upgrade
Verify Components	Check if Spicetify is properly injected with all apps/extensions

---

Quick Start

Prerequisites

• Windows 10/11
• PowerShell 5.1+ (included with Windows)
• Spotify Desktop (not the Microsoft Store version — the manager will help you switch)
• Do NOT run as Administrator — Spicetify refuses admin and Spotify shows a black window

Install & Run — 3 formas de abrir la TUI

#	Método	Archivo	Cómo abrir
1	Doble clic (recomendado)	Spicetify-Manager.bat	Doble clic en el archivo
2	PowerShell directo	Spicetify_Manager.ps1	powershell -ExecutionPolicy Bypass -File .\Spicetify_Manager.ps1
3	Ejecutable	Spicetify-Manager.exe	Doble clic en el .exe (launcher nativo, requiere el .ps1 al lado)

Nota: los 3 lanzadores hacen lo mismo — abren la misma TUI. El .exe es un wrapper liviano (6 KB, C#) que localiza powershell/pwsh y lanza el .ps1 con -ExecutionPolicy Bypass. No requiere instalación.

1. Download the latest release or clone this repository:

   git clone https://github.com/Israleche/SpicetifyManager.git
   cd SpicetifyManager

2. Elige una de las 3 formas de arriba y ejecuta.

Alternativas por línea de comandos

# PS 5.1 / PS 7 — directo
powershell -ExecutionPolicy Bypass -File .\Spicetify_Manager.ps1
pwsh -ExecutionPolicy Bypass -File .\Spicetify_Manager.ps1

# Con parámetros
.\Spicetify_Manager.ps1 -Silent        # modo no interactivo
.\Spicetify_Manager.ps1 -ShowAbout     # pantalla About
.\Spicetify_Manager.ps1 -NoPersist     # sin guardar settings

# Via exe (reenvía args al ps1)
.\Spicetify-Manager.exe -Silent
.\Spicetify-Manager.exe -ShowAbout

---

Usage

When you launch the manager, you'll see the main menu (navigate with up/down arrows + ENTER, or number keys; ESC goes back):

  ==================================================================

   ███████╗██████╗ ██╗ ██████╗███████╗████████╗██╗███████╗██╗   ██╗
   ██╔════╝██╔══██╗██║██╔════╝██╔════╝╚══██╔══╝██║██╔════╝╚██╗ ██╔╝
   ███████╗██████╔╝██║██║     █████╗     ██║   ██║█████╗   ╚████╔╝
   ╚════██║██╔═══╝ ██║██║     ██╔══╝     ██║   ██║██╔══╝    ╚██╔╝
   ███████║██║     ██║╚██████╗███████╗   ██║   ██║██║        ██║
   ╚══════╝╚═╝     ╚═╝ ╚═════╝╚══════╝   ╚═╝   ╚═╝╚═╝        ╚═╝

                               MANAGER

  ==================================================================
  progress:ON  autofix:ON  autoopen:ON
  ==================================================================

  +--------------------------------------------------------------+
  |                         MAIN MENU                             |
  +--------------------------------------------------------------+
  | [1] Auto (spicetify auto: backup/apply/launch)               |
  | [2] Full restore & repair (restore + backup + apply)         |
  | [3] Quick repair (backup apply)                              |
  | [4] Manage themes / extensions / apps                        |
  | [5] Install / repair Marketplace                             |
  | [6] Upgrade Spicetify CLI                                    |
  | [7] Open Spicetify config folder                             |
  | [8] View status & info                                       |
  | [9] Install / fix desktop Spotify                            |
  | [S] Settings                                                 |
  | [A] Advanced options                                         |
  | [H] Help & documentation                                     |
  | [0] Exit                                                     |
  +--------------------------------------------------------------+

Menu Options

Key	Action
1	Auto — Runs spicetify auto (backup + apply + open Spotify)
2	Full Restore — restore backup → backup → apply (fixes broken patches)
3	Quick Repair — backup apply (fast fix after Spotify update)
4	Themes/Extensions/Apps — Sub-menu for themes, extensions, custom apps, Marketplace
5	Marketplace — Install or repair Spicetify Marketplace
6	Upgrade — Update Spicetify CLI to the latest version
7	Config Folder — Open Spicetify's config directory in Explorer
8	Status — Show Spicetify version, Spotify state, and detected paths
9	Spotify Desktop — Remove Store version, install Desktop version
V	Verify Components — Check if Spicetify is properly injected with all apps/extensions
S	Settings — Toggle progress output, auto-fix, auto-open
A	Advanced — Direct spicetify commands, path repair
H	Help — Documentation, troubleshooting, first-time guide
0	Exit

---

Advanced Features

Silent Mode

Run the full auto-flow non-interactively:

.\Spicetify_Manager.ps1 -Silent

This will:

1. Install Spicetify if missing
2. Fix Spotify installation if needed
3. Run spicetify auto
4. Exit automatically

Settings Persistence

Settings are saved to $HOME\.spicetify-manager\settings.json and persist across sessions:

# Load saved settings and run
.\Spicetify_Manager.ps1

Session overrides for toggles (progress, auto-fix, auto-open, debug) are changed in-app: Settings menu → toggle items. They persist to settings.json.

Advanced UI Components

The script includes professional TUI helpers:

• Progress bars — 4 styles: Blocks, Dots, Arrow, Solid
• Spinners — Animated loading indicators
• Arrow-key menus — Navigate with up/down arrows, section headers, hint bar
• Semantic badges — [ OK ] / [WARN] / [MISS] status colors
• Box drawing — Modern curved borders (╭─╮)

---

Settings

Settings are persistent — they save to JSON and load on next run.

Setting	Default	Description
ShowProgress	ON	Display spicetify CLI output as commands run
DebugMode	OFF	Enable debug logging
AutoFixSpotify	ON	Automatically detect and fix Spotify issues at startup
AutoOpenSpotify	ON	Open Spotify after apply/restore operations

Command-line parameters

.\Spicetify_Manager.ps1 -ShowAbout   # print the about box and exit
.\Spicetify_Manager.ps1 -Silent      # non-interactive auto flow

Parameter	Values	Effect
-Silent	(switch)	Run non-interactively (full auto flow)
-ShowAbout	(switch)	Show the about box and exit
-Update	(switch)	Self-update the script from GitHub and exit
-ProfileName	name	Load a saved configuration profile at startup
-NoPersist	(switch)	Don't load/save settings JSON

Toggles (ShowProgress, DebugMode, AutoFixSpotify, AutoOpenSpotify) are changed from the in-app Settings menu and persist to settings.json.

---

Troubleshooting

See docs/TROUBLESHOOTING.md for common issues and fixes.

Quick fixes:

Problem	Fix
Black Spotify window	You ran as Administrator. Re-run as normal user.
"No backup available"	Open Spotify once, log in, close it, then run option 2.
Store Spotify detected	Use option 9 to switch to Desktop version.
Spicetify not found	The manager will offer to install it automatically.
Spotify update broke themes	Run option 3 (Quick Repair) or option 2 (Full Restore).
Online catalog empty	GitHub search allows ~10 req/min unauthenticated. Wait a minute and retry.
Extension/theme from catalog looks suspicious	Don't install it — Marketplace items are community code, not validated by Spicetify.

---

How It Works

Spicetify Manager is a PowerShell wrapper around the Spicetify CLI. It:

1. Detects your Spotify installation type (Desktop vs Microsoft Store)
2. Verifies Spicetify is installed (offers to install if missing)
3. Presents a menu-driven interface for common Spicetify operations
4. Handles the Spotify process (close before patching, reopen after)
5. Auto-repairs config paths when Spotify's location changes

The script is stateful — settings persist as JSON in $HOME/.spicetify-manager/ (theme, toggles, profiles, logs, backups). Every session loads the saved settings; use -NoPersist for a stateless run without loading or saving.

---

Project Structure

Spicetify-Manager/
├── .github/
│   └── FUNDING.yml           # Sponsorship info
├── docs/
│   ├── TROUBLESHOOTING.md    # Detailed troubleshooting guide
│   └── reference/            # UI reference screenshots + index
├── .gitignore                # Git ignore rules
├── README.md                 # This file
├── Spicetify_Manager.ps1     # Main PowerShell script
├── Spicetify_Manager.Tests.ps1 # Pester 5+ test suite
├── Spicetify-Manager.bat     # Double-click launcher (forwards args via %*)
└── Spicetify-Manager.exe     # Native launcher wrapper (requires the .ps1 alongside)

# Created at runtime in the user's home folder (not in the repo):
$HOME/.spicetify-manager/
├── settings.json             # Persistent settings (theme, toggles)
├── profiles/                 # Named configuration profiles (*.json)
├── backups/                  # Config backups (auto + self-update)
└── logs/                     # Daily structured JSON logs

---

Requirements

• Windows 10 or later
• PowerShell 5.1+ (pre-installed on Windows 10/11)
• Spotify Desktop (not the Microsoft Store version)
• Internet connection (for installing Spicetify, Marketplace, or Spotify)

---

Acknowledgments

• Spicetify CLI — The core tool this manager wraps
• Spicetify Marketplace — Theme and extension browser
• Spotify — Music streaming platform

---