# spicetify/cli: customizing the official Spotify client from the terminal

> Spicetify is a command-line tool that patches the official Spotify desktop client with themes, CSS, extensions and custom apps. It is a patch-and-reapply workflow, so the interesting questions are what it can change and what happens after a Spotify update.

**spicetify/cli** — Command-line tool to customize Spotify client. Supports Windows, macOS, and Linux.

- Repository: https://github.com/spicetify/cli
- Website: https://spicetify.app
- Stars: 24,690 · Forks: 949
- Language: JavaScript
- License: LGPL-2.1
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/spicetify-cli

## What spicetify/cli actually changes in the Spotify client

The official Spotify desktop client is closed source and its interface is not user-configurable. Spicetify takes the opposite approach to building a client: it modifies the copy already installed on your machine. The README lists four capabilities, and they are worth reading as a single idea rather than four features. You can change colors across the user interface, inject CSS for advanced customization, inject extensions that extend functionality and manipulate the UI and player, and inject custom apps.

The audience follows from that. This is for people who already use the Spotify desktop app and want the interface to look or behave differently, and who are comfortable running a CLI and re-running it after updates. The repository carries Themes/, Extensions/ and CustomApps/ directories, which tells you the project expects third parties to ship those artifacts rather than expecting every user to write CSS from scratch. The homepage points at spicetify.app, and the README sends installation and basic usage to the docs site rather than inlining them, so the CLI in this repository is one half of a documentation-and-marketplace ecosystem.

What it is not: a Spotify API client, a downloader, or a replacement player. Nothing in the README describes fetching track data or controlling playback outside the client. The stated goal is narrower and clearer, "make yourself in control of the Spotify client."

## How the patch model works, and why re-apply is the recurring cost

The mechanism implied by the repository layout is a patch pipeline. The Go binary in this repository reads the installed Spotify client, writes modified assets into it, and records enough state to undo or redo the operation. The css-map.json file at the top level is the part worth noticing: it is a mapping used to locate elements in the client's stylesheets, which is exactly the kind of file that breaks when Spotify changes its markup. Themes and CSS overrides are only as stable as that map.

The extensions and custom apps are JavaScript. The jsHelper/ directory and the package.json scripts point at a wrapper build: scripts/build-wrapper.mjs produces a wrapper, and there is a check:wrapper script to verify it. The npm package is marked private, so it is a build toolchain for the project, not something you install from npm as a consumer. If you want to write an extension, that is the layer you touch, and the JS is bundled with esbuild before being injected.

Go 1.25.0 is the module's declared version, and the dependencies are small: an INI parser (github.com/go-ini/ini), a terminal color library, pterm for the CLI output, and golang.org/x packages. There is no plugin runtime, no server component and no daemon. Everything happens when you run the command, which is also why the failure mode is predictable: a Spotify update replaces the patched files, and you run the tool again.

## Installing spicetify/cli and applying a first theme

The README does not inline install commands. It links to https://spicetify.app/docs/getting-started for installation and to the same page's Basic Usage section for the first run, and the repository contains install.sh and install.ps1 at the top level, which are the scripts those instructions point at. Follow the docs page rather than reconstructing the commands; the exact flags are not in this repository's README.

Once the CLI is on your PATH, the workflow is a sequence of subcommands. The docs describe the basic usage pattern as applying the modifications and then restarting Spotify. The repository's own package.json shows the toolchain side of the project, which is what you need if you build or contribute rather than just use it:

```bash
pnpm install
pnpm run build:wrapper
pnpm run check:wrapper
```

Those scripts come straight from package.json: build:wrapper runs node scripts/build-wrapper.mjs and check:wrapper runs the same with --check. The engines field requires Node 18 or newer and pnpm 8 or newer, and the packageManager field pins pnpm@11.9.0, with npm and yarn rejected outright. That is the contributor path, not the user path.

For end users, the operation is a theme directory of CSS plus an optional color scheme, and the CLI injects extensions and custom apps the same way. The repository's Themes/, Extensions/ and CustomApps/ directories hold the ones shipped with the project. The important operational detail is that applying is not a watched or hot-reloaded process: you change configuration, run the tool, restart Spotify, and repeat. The README does not document a rollback command by name, so check the docs page for the current restore procedure before you start experimenting.

## Where spicetify/cli breaks: client updates and the beta line

The genuine limitation is structural. Spicetify patches a closed-source application that updates on its own schedule, and the project's own files show how much of the surface is version-sensitive. css-map.json exists because UI element locations have to be tracked. When Spotify ships a redesign, themes and CSS that depend on those mappings can stop applying correctly, and the fix is on Spicetify's side, not yours.

The release history makes the maintenance reality visible. Alongside v2.45.1, dated 2026-09-16, the repository publishes a v3.0.0 beta line with builds v3.0.0-beta.18 and v3.0.0-beta.19 on 2026-09-17. A stable line and a beta line moving in parallel is normal for a project this coupled to an external client, but it means "which version am I on" is a real question before you file a bug. The last push to the repository was on 2026-09-18, so work is ongoing, but that says nothing about whether your specific Spotify build is supported today.

It is also the wrong tool for several jobs. If you want to script playback, query the catalog, or run Spotify in a container or on a headless machine, this does not do that; it modifies a desktop client that still has to be installed and logged in. If you are on a platform where the Spotify desktop client is not available, the CLI has nothing to patch. And if you need the interface to stay stable across automatic updates without intervention, the patch model is working against you.

## spicetify/cli versus the Marketplace

The comparison people actually need is not against another CLI, it is against Spicetify Marketplace, the in-client way to browse themes and extensions. The difference is where the artifacts come from and who maintains the update loop.

The CLI is the lower layer. It reads local directories (Themes/, Extensions/, CustomApps/ in the repository, and wherever you keep your own), applies them to the client, and gives you a backup and restore path. You control what is installed, you can version it in your own repository, and you can write an extension against the jsHelper wrapper and bundle it with the project's build scripts. The cost is that you own the update: when Spotify changes, you re-run the tool, and when a theme breaks you debug it.

Marketplace sits on top of that mechanism and adds discovery and installation from inside Spotify. It is the better entry point if you want to try themes without managing files, and the worse one if you want a reproducible setup you can check into version control. The two are not mutually exclusive; the CLI is what makes either of them work. If you are choosing, pick the CLI when you have a specific theme or extension you maintain yourself, and the Marketplace when you are browsing.

## Licence, maintenance and upgrade cost

The repository is licensed LGPL-2.1. That is a copyleft licence with a linking exception, and it applies to the CLI code here. It does not grant you anything with respect to Spotify's client, which remains proprietary and is governed by Spotify's own terms. The README says nothing about Spotify's position on client modification, and the project's legality is a question the README does not answer. If you plan to redistribute a modified build or bundle it into a product, read the licence text and get your own advice rather than treating this paragraph as guidance.

Upgrade cost is the part to budget for. The project is not archived and the last push was on 2026-09-18, with a stable release at v2.45.1 and a beta line at v3.0.0-beta.19. Moving from 2.x to 3.0 is a major version step, and the README does not document a migration path or a rollback procedure, so the safe sequence for anyone on stable is to confirm what changed in the 3.0 release notes before switching, and to keep the backup the tool creates.

On the toolchain side, contributors need Node 18 or newer and pnpm 8 or newer: package.json declares a packageManager of pnpm@11.9.0 and explicitly rejects npm and yarn with "please-use-pnpm". The practical upgrade rhythm is set by Spotify, not by Spicetify. Expect to re-run the tool after client updates, and expect theme breakage to arrive on Spotify's schedule.

## Conclusion

Adopt spicetify/cli if you want to restyle the official Spotify desktop client or add extensions, and you accept that Spotify updates can require a re-apply and that the project ships a beta line alongside stable 2.45.1. Do not adopt it if you need a headless or scriptable Spotify interface: this patches a desktop client, and the README lists no automation use case. Before installing, confirm which release line you want, the LGPL-2.1 terms, and that your package manager path matches the install script shown in the docs.

## FAQ

### What is the Spicetify command?

spicetify is the command-line tool in this repository that customizes the official Spotify client. The README describes it as a CLI that changes UI colors, injects CSS, extensions and custom apps. Installation and basic usage are documented at spicetify.app/docs/getting-started.

### How do I install spicetify/cli?

The README does not inline the install commands; it links to https://spicetify.app/docs/getting-started. The repository ships install.sh and install.ps1 at the top level, which are the scripts those instructions use.

### How do I use spicetify/cli?

The documented basic usage pattern is to apply the modifications and then restart Spotify, with the docs page covering the sequence. Themes, extensions and custom apps are read from their respective directories and injected when you run the tool.

### Is Spicetify legal?

The repository carries an LGPL-2.1 licence covering the CLI itself. The README does not state Spotify's position on modifying its client, so that question is not answered by this material.

### Is there a Spotify CLI?

No Spotify-provided command-line client is described in this repository. spicetify/cli is a third-party tool that customizes the official desktop client rather than replacing it or exposing Spotify's API.

### What is spicetify cli?

It is a command-line tool to customize the official Spotify client, supporting Windows, macOS and Linux. Its README lists changing UI colors, injecting CSS, injecting extensions and injecting custom apps.

## Sources

- [License: LGPL-2.1](https://github.com/spicetify/cli/blob/main/LICENSE)
- [Project website](https://spicetify.app)
- [README](https://github.com/spicetify/cli/blob/main/README.md)
- [Releases](https://github.com/spicetify/cli/releases)
- [spicetify/cli on GitHub](https://github.com/spicetify/cli)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/spicetify-cli