Spicetify CLI

https://github.com/spicetify/cli
Admin
Spicetify CLI is a command-line tool that allows users to customize the official Spotify client by...
Tokens:74,956
Snippets:485
Trust Score:7.7
License:LGPL-2.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Playback control usage examples

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/player.md

Examples demonstrating how to seek to a specific position and play a URI with error handling.

```js
// Skip to 50% of the track
Spicetify.Player.seek(0.5);
// Or seek to 1:30 exactly
Spicetify.Player.seek(90000);

Spicetify.Player.playUri("spotify:track:4uLU6hMCjMI75M1A2tKUQC")
  .then(() => Spicetify.Player.togglePlay())
  .catch((err) => console.error("Play failed", err));
```

--------------------------------

### Install Lyrics Plus with spicetify config and apply

Source: https://github.com/spicetify/cli/blob/main/CustomApps/lyrics-plus/README.md

Install the Lyrics Plus custom app by configuring Spicetify and applying the changes.

```bash
spicetify config custom_apps lyrics-plus
spicetify apply
```

--------------------------------

### Build the wrapper helper

Source: https://github.com/spicetify/cli/blob/main/CONTRIBUTING.md

Commands to install dependencies and build the bundled wrapper helper after cloning the repository.

```bash
cd cli
pnpm install
pnpm build:wrapper
```

--------------------------------

### Convert URI to URL and get path

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/uri.md

JavaScript example using Spicetify.URI.fromString to create a URI object, then converting it to a full URL and extracting the path. The output shows the resulting URL and path.

```javascript
const uri = Spicetify.URI.fromString("spotify:track:4uLU6hMCjMI75M1A2tKUQC");
console.log(uri.toURL("https://open.spotify.com")); // https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC
console.log(uri.getPath());                          // /track/4uLU6hMCjMI75M1A2tKUQC
```

--------------------------------

### spicetify config usage and examples

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/commands.md

Shows the usage of the `spicetify config` command. The first block lists the general syntax for printing all fields, printing one field, or setting one or more pairs. The second block gives concrete examples: toggling `disable_sentry`, appending an extension, removing an extension with a trailing `-`, setting multiple fields, and passing launch flags with `--`.

```text
spicetify config                        # print all fields & values (grouped by section)
spicetify config <field>                # print one field
spicetify config <field> <value> [...]  # set one or more pairs
```

```bash
spicetify config disable_sentry 1
spicetify config extensions myFakeExt.js
spicetify config extensions wrongname.js-
spicetify config inject_css 0 song_page 1
spicetify config spotify_launch_flags -- "--flag-1|--flag-2"
```

--------------------------------

### Backup Start Function

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/status.md

Copies the Apps folder into the Backup folder using a non-recursive allow-list filter for .spa files.

```go
func Start(appPath, backupPath string) error
```

--------------------------------

### GraphQL Request usage example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/graphql-reacthook.md

Example of using Spicetify.GraphQL.Request with a definition and variables to fetch album data.

```js
const data = await Spicetify.GraphQL.Request(
  Spicetify.GraphQL.Definitions.getAlbumNameAndTracks,
  { uri: "spotify:album:4LuDU6mHcOMxAnE8QhxWsR", offset: 0, limit: 50 },
);
```

--------------------------------

### GraphQL custom handler example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/graphql-reacthook.md

Example of creating a custom GraphQL handler with its own context and using it to query track artists.

```js
// Custom handler with its own context
const handler = Spicetify.GraphQL.Handler({ ...Spicetify.GraphQL.Context, operationName: "query_my_op" });
const res = await handler(Spicetify.GraphQL.Definitions.queryTrackArtists, { uri });
```

--------------------------------

### Playbar.Widget usage example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/topbar-playbar.md

JavaScript example creating a Playbar.Widget that toggles the player's heart state and updates its active state accordingly.

```javascript
const favWidget = new Spicetify.Playbar.Widget("Toggle favorite", "heart-add", (self) => {
  Spicetify.Player.toggleHeart();
  self.active = Spicetify.Player.getHeart();
});
```

--------------------------------

### Player event listener example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/player.md

JavaScript example showing how to listen for the 'onplaypause' event and guard against undefined data before the first track. Uses optional chaining to check e.data?.isPaused.

```javascript
// Guard against events that may carry undefined data before the first track
Spicetify.Player.addEventListener("onplaypause", (e) => {
  if (e.data?.isPaused) myPauseUi();
});
```

--------------------------------

### Usage example for Spicetify.ReactComponent

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/react-components.md

Shows how to create React elements using Spicetify.ReactComponent.ButtonPrimary and TooltipWrapper. The first example creates a play/pause button, the second a tooltip-wrapped menu item that adds a track to the queue.

```javascript
Spicetify.React.createElement(
  Spicetify.ReactComponent.ButtonPrimary,
  {
    buttonSize: "sm",
    onClick: () => Spicetify.Player.togglePlay(),
    "aria-label": "Toggle play",
  },
  "Play/Pause",
);

// Tooltip-wrapped menu item
Spicetify.React.createElement(
  Spicetify.ReactComponent.TooltipWrapper,
  { label: "Add to queue", placement: "bottom" },
  Spicetify.React.createElement("button", { onClick: () => Spicetify.addToQueue([{ uri: track.uri }]) }, "＋"),
);
```

--------------------------------

### Playbar.Button usage example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/topbar-playbar.md

JavaScript example creating a Playbar.Button that toggles loop points and toggles its active state. The button can be deregistered later.

```javascript
const loopBtn = new Spicetify.Playbar.Button("Loop A→B", "repeat", (self) => {
  toggleLoopPoints();
  self.active = !self.active;   // visually toggle active state
});
// later
loopBtn.deregister();
```

--------------------------------

### Start function signature

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/preprocess.md

Entry point for preprocessing. Takes the Spicetify version, Spotify base path, extracted apps path, and flags. The version "Dev" skips remote CSS-map fetch.

```go
func Start(version string, spotifyBasePath string, extractedAppsPath string, flags Flag)
```

--------------------------------

### GET https://api.github.com/repos/spicetify/cli/releases

Source: https://github.com/spicetify/cli/blob/main/_autodocs/endpoints.md

Fetches a list of releases for the spicetify/cli repository. Used by the CLI to select the newest patch release matching the installed Spotify major.minor version when the latest release's major.minor differs.

```APIDOC
## GET https://api.github.com/repos/spicetify/cli/releases

### Description
Fetches a list of releases for the spicetify/cli repository. Used by the CLI to select the newest patch release matching the installed Spotify major.minor version when the latest release's major.minor differs.

### Method
GET

### Endpoint
https://api.github.com/repos/spicetify/cli/releases

### Parameters
No parameters.

### Response
#### Success Response (200)
- **tag_name** (string) - Release tag in the format `v<semver>`.
- **message** (string) - Present on error responses.

#### Response Example
[
  {
    "tag_name": "v2.0.0",
    "message": ""
  }
]
```

--------------------------------

### Log Spicetify version and theme from Config

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/apptitle-misc.md

Example usage of Spicetify.Config to log the version and current theme. Uses optional chaining to safely access version and checks it is not 'Dev'.

```javascript
if (Spicetify.Config?.version && Spicetify.Config.version !== "Dev") {
  console.log(`Spicetify ${Spicetify.Config.version} — theme ${Spicetify.Config.current_theme}`);
}
```

--------------------------------

### StartCSS function signature

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/preprocess.md

Applies CSS-level color-variable replacement to the Themed asset tree after cmd.Backup copies Raw to Themed. Uses the CSS map loaded at Start time.

```go
func StartCSS(extractedAppsPath string)
```

--------------------------------

### CosmosAsync Simple GET and POST

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/cosmos-async.md

The wrapper uses this GET internally. The GET request targets a spclient URL and passes query parameters. The POST sends a JSON body to an internal sp: endpoint with a custom header. Note that GET bodies are serialized to URL query params; other methods send JSON with Content-Type application/json.

```js
// Simple GET (the wrapper also uses this internally):
const colors = await Spicetify.CosmosAsync.get(
  "https://spclient.wg.spotify.com/colorextractor/v1/extract-presets?uri=spotify:album:4LuDU6mHcOMxAnE8QhxWsR&format=json",
);

// POST with JSON body and custom header
await Spicetify.CosmosAsync.post(
  "sp://core-playlist/v1/rootlist",
  { operation: "add", ... },
  { "X-Custom": "value" },
);
```

--------------------------------

### ContextMenu Item and SubMenu usage examples

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/menus.md

JavaScript usage examples for ContextMenu. The basic item registers a click handler that pushes URIs to a queue. The second item uses a predicate to show only for tracks and sets the heart icon. The submenu contains two items and is shown when the selection has at least one URI.

```js
// Basic item
new Spicetify.ContextMenu.Item("Add to my list", (uris, uids, contextUri) => {
  uris.forEach((u) => queue.push(u));
}).register();

// With predicate + icon + submenu
new Spicetify.ContextMenu.Item(
  "Save track",
  (uris) => Spicetify.Player.setHeart(true),
  (uris) => uris.some((u) => Spicetify.URI.isTrack(u)),
  "heart",
).register();

const sub = new Spicetify.ContextMenu.SubMenu(
  "More",
  [
    new Spicetify.ContextMenu.Item("Option A", () => {}),
    new Spicetify.ContextMenu.Item("Option B", () => {}),
  ],
  (uris) => uris.length > 0,
);
sub.register();
```

--------------------------------

### useMyPlaylists hook using ReactQuery.useQuery

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/graphql-reacthook.md

Example hook that uses Spicetify.ReactQuery.useQuery to fetch playlists from the Spotify rootlist endpoint via CosmosAsync.get.

```javascript
function useMyPlaylists() {
  return Spicetify.ReactQuery.useQuery({
    queryKey: ["playlists"],
    queryFn: () => Spicetify.CosmosAsync.get("sp://core-playlist/v1/rootlist"),
  });
}
```

--------------------------------

### Keyboard shortcut registration and management example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/keyboard.md

Shows how to register shortcuts with object and string key definitions, change a shortcut, and deregister a shortcut. The first registration uses ctrl+shift+S and calls toggleShufflePlus. The second registers F9. changeShortcut rebinds F9 to alt+F10, and _deregisterShortcut removes that binding.

```javascript
Spicetify.Keyboard.registerShortcut({ key: "S", ctrl: true, shift: true }, (e) => {
  e.preventDefault();
  toggleShufflePlus();
});

Spicetify.Keyboard.registerShortcut("F9", () => runRoutine());
Spicetify.Keyboard.changeShortcut("F9", { key: "F10", alt: true });
Spicetify.Keyboard._deregisterShortcut({ key: "F10", alt: true });
```

--------------------------------

### GET https://github.com/spicetify/cli/releases/download/v<tag>/spicetify-<tag>-<goos>-<arch>.{zip,tar.gz}

Source: https://github.com/spicetify/cli/blob/main/_autodocs/endpoints.md

Downloads a release asset for the spicetify/cli repository. Used by the CLI `update` command to fetch the appropriate binary archive for the current platform.

```APIDOC
## GET https://github.com/spicetify/cli/releases/download/v<tag>/spicetify-<tag>-<goos>-<arch>.{zip,tar.gz}

### Description
Downloads a release asset for the spicetify/cli repository. Used by the CLI `update` command to fetch the appropriate binary archive for the current platform.

### Method
GET

### Endpoint
https://github.com/spicetify/cli/releases/download/v<tag>/spicetify-<tag>-<goos>-<arch>.{zip,tar.gz}

### Parameters
#### Path Parameters
- **tag** (string) - Required - Release tag without the leading `v`.
- **goos** (string) - Required - Operating system: `windows`, `linux`, or `darwin`.
- **arch** (string) - Required - Architecture: `x32` (windows/386), `arm64`, `x64` (windows/amd64), or `amd64`.

### Response
#### Success Response (200)
Binary file content (zip or tar.gz).

### Error Handling
Any status other than 200 aborts the update with a fatal error: `"unexpected HTTP status: <status> for <url>"`.
```

--------------------------------

### Topbar.Button usage example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/topbar-playbar.md

JavaScript example creating a Topbar.Button with a click handler that disables the button during an async operation. Buttons are registered on construction.

```javascript
const btn = new Spicetify.Topbar.Button("Play Shuffle+", "shuffle", (self) => {
  self.disabled = true;              // visualize busy state
  playWithShufflePlus().finally(() => { self.disabled = false; });
});
// Topbar buttons are always registered on construction.
```

--------------------------------

### Using Spicetify.Color.fromCSS, toCSS, and contrastAdjust

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/locale-color.md

JavaScript example showing how to create a Color from a CSS color string, convert it to HEX format, and adjust contrast against black. The output of toCSS is shown as a comment.

```javascript
const c = Spicetify.Color.fromCSS("rgb(30,215,96)");
console.log(c.toCSS(Spicetify.Color.CSSFormat.HEX));        // "#1db954"
const darker = c.contrastAdjust(Spicetify.Color.BLACK, 4.5);
```

--------------------------------

### getAudioData Usage Example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/spicetify-global.md

Fetches audio data for a specific track URI and logs the result. Rejects with the string "URI is invalid." when the URI cannot be parsed or is not a TRACK.

```javascript
const audio = await Spicetify.getAudioData("spotify:track:4uLU6hMCjMI75M1A2tKUQC");
console.log(audio);
```

--------------------------------

### Using Spicetify.showNotification

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/spicetify-global.md

Example calls to Spicetify.showNotification: a success notification with a 2000ms timeout and an error notification using the default timeout.

```javascript
Spicetify.showNotification("Track added to queue ✓", false, 2000);
Spicetify.showNotification("Failed to load", true);
```

--------------------------------

### GET https://spclient.wg.spotify.com/colorextractor/v1/extract-presets?uri=<uri>&format=json

Source: https://github.com/spicetify/cli/blob/main/_autodocs/endpoints.md

Fetches color presets for a given Spotify URI. Used by Spicetify.colorExtractor. Returns a mapping of color preset names to hex strings.

```APIDOC
## GET https://spclient.wg.spotify.com/colorextractor/v1/extract-presets?uri=<uri>&format=json

### Description
Fetches color presets for a given Spotify URI. Used by Spicetify.colorExtractor. Returns a mapping of color preset names to hex strings.

### Method
GET

### Endpoint
https://spclient.wg.spotify.com/colorextractor/v1/extract-presets?uri=<uri>&format=json

### Parameters
#### Query Parameters
- **uri** (string) - Required - The Spotify URI.
- **format** (string) - Required - Must be `json`.

### Authentication
- **Authorization** (header) - Bearer token.
- **Spotify-App-Version** (header) - Required.
- **App-Platform** (header) - Required.

### Response
#### Success Response (200)
- **entries** (array) - Array of objects with `color_swatches`.
  - **color_swatches** (array) - Array of objects with `preset` and `color`.
    - **preset** (string) - Preset name.
    - **color** (string) - Color value.

#### Response Example
{
  "entries": [
    {
      "color_swatches": [
        {
          "preset": "DARK_VIBRANT",
          "color": "#000000"
        }
      ]
    }
  ]
}

### Notes
- Resolves to an object with keys: DARK_VIBRANT, DESATURATED, LIGHT_VIBRANT, PROMINENT, VIBRANT, VIBRANT_NON_ALARMING (hex strings).
- Returns `null` when `entries` is empty.
```

--------------------------------

### Listen to webpackLoaded event

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/apptitle-misc.md

Example of using Spicetify.Events.webpackLoaded to safely use Spicetify.React or Spicetify.ReactComponent after webpack modules are loaded.

```javascript
Spicetify.Events.webpackLoaded.on(() => {
  // Safe to use Spicetify.React / Spicetify.ReactComponent now
  mountMyExtension();
});
```

--------------------------------

### React-based settings dialog

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/popup.md

Example of a React-based settings dialog using Spicetify.React and Spicetify.ReactComponent. The modal is displayed with isLarge: true.

```javascript
// React-based settings dialog with per-section styling
function SettingsModal() {
  const [value, setValue] = Spicetify.React.useState("");
  return Spicetify.React.createElement(
    Spicetify.ReactComponent.TextComponent,
    { as: "div", variant: "brio" },
    Spicetify.React.createElement("input", { value, onChange: (e) => setValue(e.target.value) }),
  );
}
Spicetify.PopupModal.display({ title: "React settings", content: Spicetify.React.createElement(SettingsModal), isLarge: true });
```

--------------------------------

### extractColorPreset usage example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/graphql-reacthook.md

Demonstrates calling Spicetify.extractColorPreset with a Spotify album URI. The returned preset is checked for isFallback before applying the color as a CSS hex value.

```JavaScript
const [preset] = await Spicetify.extractColorPreset("spotify:album:4LuDU6mHcOMxAnE8QhxWsR");
if (!preset.isFallback) applyCssColor(preset.colorRaw.toCSS(Spicetify.Color.CSSFormat.HEX));
```

--------------------------------

### colorExtractor Usage Example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/spicetify-global.md

Queries the color-presets endpoint for an album URI and extracts the PROMINENT color, falling back to a default hex if null.

```javascript
const colors = await Spicetify.colorExtractor("spotify:album:4LuDU6mHcOMxAnE8QhxWsR");
const dominant = colors?.PROMINENT ?? "#535353";
```

--------------------------------

### Spicetify.Locale

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/locale-color.md

Complete API reference for the Spicetify.Locale namespace, including all functions, parameters, return types, and usage examples.

```APIDOC
## Locale

### Description
Provides locale-aware formatting and translation functions for the Spicetify client.

### Functions

#### formatDate(date: number | Date | undefined, options?: Intl.DateTimeFormatOptions): string
- **date** (number | Date | undefined) - Required - The date to format.
- **options** (Intl.DateTimeFormatOptions) - Optional - Formatting options.
- **Returns**: Formatted date string.
- **Throws**: `RangeError` on invalid dates.

#### formatRelativeTime(date: number | Date | undefined, options?: Intl.DateTimeFormatOptions): string
- **date** (number | Date | undefined) - Required - The date to format relative to now.
- **options** (Intl.DateTimeFormatOptions) - Optional - Formatting options.
- **Returns**: Relative time string (e.g., "1 minute ago").
- **Throws**: `RangeError` on invalid dates.

#### formatNumber(number: number, options?: Intl.NumberFormatOptions): string
- **number** (number) - Required - The number to format.
- **options** (Intl.NumberFormatOptions) - Optional - Formatting options.
- **Returns**: Locale-aware formatted number string.

#### formatNumberCompact(number: number): string
- **number** (number) - Required - The number to format compactly.
- **Returns**: Compact formatted number string (e.g., "1.2M").

#### get(key: string, ...children: React.ReactNode[]): string | React.ReactNode
- **key** (string) - Required - The translation key.
- **children** (React.ReactNode[]) - Optional - Fallback content if key is missing.
- **Returns**: Localized string or fallback React node.

#### getDateTimeFormat(options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormat
- **options** (Intl.DateTimeFormatOptions) - Optional - Formatting options.
- **Returns**: An `Intl.DateTimeFormat` instance.

#### getDictionary(): Record<string, string | { one: string; other: string }>
- **Returns**: The current translation dictionary.

#### getLocale(): string
- **Returns**: The current locale code.

#### getSmartlingLocale(): string
- **Returns**: The Smartling locale code.

#### getUrlLocale(): string
- **Returns**: The locale code used for URLs.

#### getRelativeTimeFormat(): Intl.RelativeTimeFormat
- **Returns**: An `Intl.RelativeTimeFormat` instance.

#### getSeparator(): string
- **Returns**: The locale-specific separator string.

#### setLocale(locale: string): void
- **locale** (string) - Required - The new locale code.
- **Note**: Clears cached formats. No-op if translator not detected.

#### setUrlLocale(locale: string): void
- **locale** (string) - Required - The new URL locale code.

#### setDictionary(dictionary: Record<string, string | { one: string; other: string }>): void
- **dictionary** (Record<string, string | { one: string; other: string }>) - Required - The new translation dictionary.
- **Note**: Re-initializes the translator. No-op if translator not detected.

#### toLocaleLowerCase(text: string): string
- **text** (string) - Required - The text to convert.
- **Returns**: Locale-aware lowercase string.

#### toLocaleUpperCase(text: string): string
- **text** (string) - Required - The text to convert.
- **Returns**: Locale-aware uppercase string.

### Example
```js
const label = Spicetify.Locale.get("empty-state.title");
const time = Spicetify.Locale.formatRelativeTime(Date.now() - 60_000);
const compact = Spicetify.Locale.formatNumberCompact(1_234_567); // "1.2M"
```
```

--------------------------------

### AppTitle namespace

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/apptitle-misc.md

Interface for interacting with the client window title. Provides methods to set, reset, get, and subscribe to title changes.

```APIDOC
## AppTitle namespace

### Description
Interface for interacting with the client window title. Provides methods to set, reset, get, and subscribe to title changes.

### Methods

#### set(title: string): Promise<{ clear: () => void }>
Overrides the product-state `name` value and subscribes; resolves to a subscription handle (`clear()` cancels it) — the handle does **not** reset the title.

#### reset(): Promise<void>
Cancels the subscription and deletes the `name` override (`delOverridesValues`).

#### get(): Promise<string>
Reads `name` from `productState.getValues()`.

#### sub(callback: (title: string) => void): { clear: () => void }
Subscribes to product-state `name` changes; returns the subscription handle with `clear()`.

### Example
```js
const titleCtl = await Spicetify.AppTitle.set("My Extension");
// … later
titleCtl.clear();

const sub = Spicetify.AppTitle.sub((title) => console.log("title →", title));
sub.clear();
```
```

--------------------------------

### GET https://spclient.wg.spotify.com/audio-attributes/v1/audio-analysis/{base62Id}?format=json

Source: https://github.com/spicetify/cli/blob/main/_autodocs/endpoints.md

Fetches audio analysis data for a track. Used by Spicetify.getAudioData. Requires authentication via Bearer token and spclient headers.

```APIDOC
## GET https://spclient.wg.spotify.com/audio-attributes/v1/audio-analysis/{base62Id}?format=json

### Description
Fetches audio analysis data for a track. Used by Spicetify.getAudioData. Requires authentication via Bearer token and spclient headers.

### Method
GET

### Endpoint
https://spclient.wg.spotify.com/audio-attributes/v1/audio-analysis/{base62Id}?format=json

### Parameters
#### Path Parameters
- **base62Id** (string) - Required - The base62 ID of the track.

#### Query Parameters
- **format** (string) - Required - Must be `json`.

### Authentication
- **Authorization** (header) - Bearer token.
- **Spotify-App-Version** (header) - Required.
- **App-Platform** (header) - Required.

### Response
#### Success Response (200)
- **body** (any) - Analyzed audio JSON.

### Error Handling
- Rejects with "URI is invalid." before the request if the URI is not a track.
```

--------------------------------

### GET https://api.github.com/repos/spicetify/cli/releases/latest

Source: https://github.com/spicetify/cli/blob/main/_autodocs/endpoints.md

Fetches the latest release metadata for the spicetify/cli repository. Used by the CLI for update checks and by the in-client update card.

```APIDOC
## GET https://api.github.com/repos/spicetify/cli/releases/latest

### Description
Fetches the latest release metadata for the spicetify/cli repository. Used by the CLI for update checks and by the in-client update card.

### Method
GET

### Endpoint
https://api.github.com/repos/spicetify/cli/releases/latest

### Parameters
No parameters.

### Response
#### Success Response (200)
- **tag_name** (string) - Release tag in the format `v<semver>`; the CLI strips the leading `v`. Empty value indicates an error with message `"GitHub response: <message>"`.
- **message** (string) - Present on error responses (e.g., rate limit).

#### Response Example
{
  "tag_name": "v2.0.0",
  "message": ""
}

### Error Handling
Non-JSON or network errors surface as Go errors with message `"Cannot fetch latest release info"`.
```

--------------------------------

### Set and subscribe to AppTitle

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/apptitle-misc.md

Example of setting the app title and subscribing to title changes. The set function returns a handle with clear() to cancel the override; sub returns a handle with clear() to unsubscribe.

```javascript
const titleCtl = await Spicetify.AppTitle.set("My Extension");
// … later
titleCtl.clear();

const sub = Spicetify.AppTitle.sub((title) => console.log("title →", title));
sub.clear();
```

--------------------------------

### classnames usage example

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/graphql-reacthook.md

Shows how to use Spicetify.classnames to conditionally join class names. The second argument is an object where keys are class names and values are booleans; here it adds the active class when isActive is true.

```JavaScript
Spicetify.classnames("link-subtle", { "main-yourLibraryX-navLinkActive": isActive });
```

--------------------------------

### TrackCard component using useExtractedColor

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/graphql-reacthook.md

Example component that uses Spicetify.ReactHook.useExtractedColor to get a color and sets it as the background of a div. The color is extracted from the given URI with fallback '#535353' and variant 'colorDark'.

```javascript
function TrackCard({ uri }) {
  const color = Spicetify.ReactHook.useExtractedColor(uri, "#535353", "colorDark");
  return Spicetify.React.createElement("div", { style: { backgroundColor: color } }, uri);
}
```

--------------------------------

### Using Spicetify.Locale methods

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/locale-color.md

Example usage of Spicetify.Locale methods: get a localized string, format a relative time, and format a compact number. The comment shows the expected output for formatNumberCompact with 1,234,567.

```javascript
const label = Spicetify.Locale.get("empty-state.title");
const time = Spicetify.Locale.formatRelativeTime(Date.now() - 60_000);
const compact = Spicetify.Locale.formatNumberCompact(1_234_567); // "1.2M"
```

--------------------------------

### CosmosAsync error handling with get

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/cosmos-async.md

Shows the proper pattern when the response resolves with an error object (code, message) instead of rejecting for HTTP errors. The example checks `res.code` and shows a notification, otherwise processes data. Internal cosmos endpoints keep their own rejection semantics.

```js
const res = await Spicetify.CosmosAsync.get("https://api.spotify.com/v1/me");
if (res.code) {
  Spicetify.showNotification(`HTTP ${res.code}: ${res.message}`, true);
  return;
}
handleData(res);
```

--------------------------------

### Create and play a track URI

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/uri.md

Demonstrates creating a track URI with an anchor, context, and autoplay setting, then playing it using the Spicetify Player.

```js
const uri = Spicetify.URI.trackURI("4uLU6hMCjMI75M1A2tKUQC", "1:30", "spotify:album:4LuDU6mHcOMxAnE8QhxWsR", true);
Spicetify.Player.playUri(uri.toURI());
```

--------------------------------

### Build the project on Windows

Source: https://github.com/spicetify/cli/blob/main/CONTRIBUTING.md

Command to compile the project into an executable for Windows systems.

```bash
go build -o spicetify.exe
```

--------------------------------

### Usage forms from help()

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/commands.md

Shows the two usage forms for the Spicetify CLI. The first form accepts optional flags and a command; the second form is for config, version, or help.

```text
spicetify [-q] [-e] [-a] command...
spicetify {-c | --config} | {-v | --version} | {-h | --help}
```

--------------------------------

### Build the project on Linux and MacOS

Source: https://github.com/spicetify/cli/blob/main/CONTRIBUTING.md

Command to compile the project into an executable for Linux and MacOS systems.

```bash
go build -o spicetify
```

--------------------------------

### Render icon using Spicetify.SVGIcons

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/spicetify-global.md

Example of using a heart icon from the SVGIcons map within an SVG element.

```js
const svg = `<svg height="16" width="16" viewBox="0 0 16 16" fill="currentColor">${Spicetify.SVGIcons.heart}</svg>`;
```

--------------------------------

### spicetify path usage

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/commands.md

Shows the usage of the `spicetify path` command. It prints the executable directory, the SPICETIFY_CONFIG folder, all theme/extension/app paths, or specific paths for extensions (`-e`), custom apps (`-a`), the active theme (`-s`), or the config file (`-c`). Invalid kinds return errors and cause a fatal exit.

```text
spicetify path                      # executable dir
spicetify path userdata             # SPICETIFY_CONFIG folder
spicetify path all                  # theme + extensions + apps paths
spicetify path -e [name|root|all…]  # extensions
spicetify path -a [name|root|…]     # custom apps
spicetify path -s [root|folder|color|css|js|assets]  # active theme
spicetify path -c                   # config (flag only)
```

--------------------------------

### Check URI type before enqueueing

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/uri.md

Example of using type predicates to verify if a URI is a track or episode before performing an action.

```js
if (Spicetify.URI.isTrack(context.uri) || Spicetify.URI.isEpisode(context.uri)) {
  enqueue(context.uri);
}
```

--------------------------------

### ReactFlipToolkit

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/graphql-reacthook.md

Provides Flipper, Flipped, and spring from the react-flip-toolkit library for magic-move layout transitions.

```APIDOC
## ReactFlipToolkit

### Description
Lightweight magic-move layout-transition library (`react-flip-toolkit`). `Flipper`/`Flipped` resolved from modules with `getSnapshotBeforeUpdate` / `displayName === "Flipped"` (`spicetify-bindings.js:64`).

### Signature
```ts
const Flipper: any; const Flipped: any; const spring: any;
```

```

--------------------------------

### Spicetify.URI constructor

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/uri.md

Creates a new URI instance. Direct construction is uncommon; use static factories instead.

```APIDOC
## Spicetify.URI constructor

### Description
Creates a new URI instance. Direct construction is uncommon; use static factories instead.

### Constructor
```ts
constructor(type: string, props: any);
```

### Parameters
- **type** (string) - Required - The URI type (see `Type` constants)
- **props** (any) - Required - Type-specific properties (`id`, `username`, `args`, `context`, …)

### Instance Fields
All optional, set per type: `id`, `disc`, `args`, `category`, `username`, `track`, `artist`, `album`, `duration`, `query`, `country`, `global`, `context: string | typeof URI | null`, `anchor`, `play`, `toplist`.
```

--------------------------------

### Config interface and parsing functions

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/utils.md

Defines the Config interface and key functions for reading and writing Spicetify configuration. ParseConfig builds default keys from configLayout when missing and rewrites the file. Platform detection covers Windows (APPDATA\Spotify, Store variant), Linux (whereis spotify plus well-known paths incl. flatpak/snap/spotify-launcher), and macOS (/Applications/Spotify.app/Contents/Resources).

```go
type Config interface {
	Write() error
	GetSection(string) *ini.Section
	GetPath() string
}
func ParseConfig(configPath string) Config
func FindAppPath() string       // auto-detect Spotify install dir
func FindPrefFilePath() string  // auto-detect prefs file
func WinXApp() string           // Microsoft Store (AppX) install location via PowerShell
func WinXPrefs() string         // AppX prefs path
```

--------------------------------

### Display modal with HTML content

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/popup.md

Example of displaying a modal with a title and HTML string content. The content is set via innerHTML.

```javascript
Spicetify.PopupModal.display({
  title: "About my extension",
  content: "<p>Version 1.0.0</p><ul><li>Feature A</li></ul>",
});
```

--------------------------------

### Backup Restore Function

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/status.md

Restores the stock layout by removing the applied Apps folder and copying .spa archives back from the backup.

```go
// in src/cmd/backup.go — restore
func Restore()
```

--------------------------------

### Spicetify.URI Factory Statics and Type Predicates

Source: https://github.com/spicetify/cli/blob/main/_autodocs/api-reference/uri.md

Factory static methods for creating Spotify URIs and type predicates for checking URI types.

```APIDOC
## albumURI(id: string, disc: number): URI

### Description
Creates a Spotify album URI with the given album ID and disc number.

### Method
Factory static method

### Endpoint
`Spicetify.URI.albumURI(id, disc)`

### Parameters
- **id** (string) - Required - The album ID.
- **disc** (number) - Required - The disc number.

### Returns
- **URI** - A URI object representing `spotify:album:<id>`.
```

```APIDOC
## applicationURI(id: string, args: string[]): URI

### Description
Creates a Spotify application URI with the given application ID and arguments.

### Method
Factory static method

### Endpoint
`Spicetify.URI.applicationURI(id, args)`

### Parameters
- **id** (string) - Required - The application ID.
- **args** (string[]) - Required - An array of arguments.

### Returns
- **URI** - A URI object representing `spotify:app:<id>`.
```

```APIDOC
## artistURI(id: string): URI

### Description
Creates a Spotify artist URI with the given artist ID.

### Method
Factory static method

### Endpoint
`Spicetify.URI.artistURI(id)`

### Parameters
- **id** (string) - Required - The artist ID.

### Returns
- **URI** - A URI object representing `spotify:artist:<id>`.
```

```APIDOC
## collectionURI(username: string, category: string): URI

### Description
Creates a Spotify collection URI for a user's collection category.

### Method
Factory static method

### Endpoint
`Spicetify.URI.collectionURI(username, category)`

### Parameters
- **username** (string) - Required - The username.
- **category** (string) - Required - The collection category.

### Returns
- **URI** - A URI object representing `spotify:user:<user>:collection:<cat>`.
```

```APIDOC
## collectionAlbumURI(username: string, id: string): URI

### Description
Creates a Spotify collection album URI for a user's collection album.

### Method
Factory static method

### Endpoint
`Spicetify.URI.collectionAlbumURI(username, id)`

### Parameters
- **username** (string) - Required - The username.
- **id** (string) - Required - The album ID.

### Returns
- **URI** - A URI object representing a collection album.
```

```APIDOC
## concertURI(id: string): URI

### Description
Creates a Spotify concert URI with the given concert ID.

### Method
Factory static method

### Endpoint
`Spicetify.URI.concertURI(id)`

### Parameters
- **id** (string) - Required - The concert ID.

### Returns
- **URI** - A URI object representing a concert.
```

```APIDOC
## episodeURI(id: string): URI

### Description
Creates a Spotify episode URI with the given episode ID.

### Method
Factory static method

### Endpoint
`Spicetify.URI.episodeURI(id)`

### Parameters
- **id** (string) - Required - The episode ID.

### Returns
- **URI** - A URI object representing an episode.
```

```APIDOC
## folderURI(id: string): URI

### Description
Creates a Spotify folder URI with the given folder ID.

### Method
Factory static method

### Endpoint
`Spicetify.URI.folderURI(id)`

### Parameters
- **id** (string) - Required - The folder ID.

### Returns
- **URI** - A URI object representing a folder.
```

```APIDOC
## localAlbumURI(artist: string, album: string): URI

### Description
Creates a Spotify local album URI with the given artist and album names.

### Method
Factory static method

### Endpoint
`Spicetify.URI.localAlbumURI(artist, album)`

### Parameters
- **artist** (string) - Required - The artist name.
- **album** (string) - Required - The album name.

### Returns
- **URI** - A URI object representing a local album.
```

```APIDOC
## localArtistURI(artist: string): URI

### Description
Creates a Spotify local artist URI with the given artist name.

### Method
Factory static method

### Endpoint
`Spicetify.URI.localArtistURI(artist)`

### Parameters
- **artist** (string) - Required - The artist name.

### Returns
- **URI** - A URI object representing a local artist.
```

```APIDOC
## playlistV2URI(id: string): URI

### Description
Creates a Spotify playlist V2 URI with the given playlist ID.

### Method
Factory static method

### Endpoint
`Spicetify.URI.playlistV2URI(id)`

### Parameters
- **id** (string) - Required - The playlist ID.

### Returns
- **URI** - A URI object representing `spotify:playlist:<id>`.
```

```APIDOC
## prereleaseURI(id: string): URI

### Description
Creates a Spotify prerelease URI with the given prerelease ID.

### Method
Factory static method

### Endpoint
`Spicetify.URI.prereleaseURI(id)`

### Parameters
- **id** (string) - Required - The prerelease ID.

### Returns
- **URI** - A URI object representing a prerelease.
```

```APIDOC
## profileURI(username: string, args: string[]): URI

### Description
Creates a Spotify profile URI with the given username and arguments.

### Method
Factory static method

### Endpoint
`Spicetify.URI.profileURI(username, args)`

### Parameters
- **username** (string) - Required - The username.
- **args** (string[]) - Required - An array of arguments.

### Returns
- **URI** - A URI object representing a profile.
```

```APIDOC
## searchURI(query: string): URI

### Description
Creates a Spotify search URI with the given query string.

### Method
Factory static method

### Endpoint
`Spicetify.URI.searchURI(query)`

### Parameters
- **query** (string) - Required - The search query.

### Returns
- **URI** - A URI object representing `spotify:search:<query>`.
```

```APIDOC
## showURI(id: string): URI

### Description
Creates a Spotify show URI with the given show ID.

### Method
Factory static method

### Endpoint
`Spicetify.URI.showURI(id)`

### Parameters
- **id** (string) - Required - The show ID.

### Returns
- **URI** - A URI object representing a show.
```

```APIDOC
## stationURI(args: string[]): URI

### Description
Creates a Spotify station URI with the given arguments.

### Method
Factory static method

### Endpoint
`Spicetify.URI.stationURI(args)`

### Parameters
- **args** (string[]) - Required - An array of arguments.

### Returns
- **URI** - A URI object representing a station.
```

```APIDOC
## trackURI(id: string, anchor: string, context?: string, play?: boolean): URI

### Description
Creates a Spotify track URI with the given track ID, optional anchor, context, and autoplay flag.

### Method
Factory static method

### Endpoint
`Spicetify.URI.trackURI(id, anchor, context?, play?)`

### Parameters
- **id** (string) - Required - The track ID.
- **anchor** (string) - Required - The anchor time in `mm:ss` format.
- **context** (string) - Optional - The context URI.
- **play** (boolean) - Optional - Whether to autoplay.

### Returns
- **URI** - A URI object representing `spotify:track:<id>` with optional anchor, context, and autoplay.
```

```APIDOC
## isAd(uri) / isAlbum(uri) / isGenre(uri) / isQueue(uri) / isApplication(uri) / isArtist(uri) / isArtistToplist(uri) / isArtistConcerts(uri) / isAudioFile(uri) / isCollection(uri) / isCollectionAlbum(uri) / isCollectionArtist(uri) / isCollectionMissingAlbum(uri) / isCollectionTrackList(uri) / isConcert(uri) / isContextGroup(uri) / isDailyMix(uri) / isEmpty(uri) / isEpisode(uri) / isFacebook(uri) / isFolder(uri) / isFollowers(uri) / isFollowing(uri) / isImage(uri) / isInbox(uri) / isInterruption(uri) / isLibrary(uri) / isLive(uri) / isRoom(uri) / isExpression(uri) / isLocal(uri) / isLocalTrack(uri) / isLocalAlbum(uri) / isLocalArtist(uri) / isMerch(uri) / isMosaic(uri) / isPlaylist(uri) / isPlaylistV2(uri) / isPrerelease(uri) / isProfile(uri) / isPublishedRootlist(uri) / isRadio(uri) / isRootlist(uri) / isSearch(uri) / isShow(uri) / isSocialSession(uri) / isSpecial(uri) / isStarred(uri) / isStation(uri) / isTempPlaylist(uri) / isToplist(uri) / isTrack(uri) / isTrackset(uri) / isUserToplist(uri) / isUserTopTracks(uri) / isUnknown(uri) / isMedia(uri) / isQuestion(uri) / isPoll(uri): boolean

### Description
Type predicates that check whether a given URI is of a specific type. All accept `URI | string` and return a boolean.

### Method
Static type predicate method

### Endpoint
`Spicetify.URI.isAd(uri)` etc.

### Parameters
- **uri** (URI | string) - Required - The URI to check.

### Returns
- **boolean** - `true` if the URI matches the type, `false` otherwise.
```

```APIDOC
## isPlaylistV1OrV2(uri: URI | string): boolean

### Description
Checks whether the given URI is a playlist V1 or V2 URI.

### Method
Static type predicate method

### Endpoint
`Spicetify.URI.isPlaylistV1OrV2(uri)`

### Parameters
- **uri** (URI | string) - Required - The URI to check.

### Returns
- **boolean** - `true` if the URI is a playlist V1 or V2, `false` otherwise.
```

--------------------------------

### FetchLatestTagMatchingOrMain function signature

Source: https://github.com/spicetify/cli/blob/main/_autodocs/cli/preprocess.md

Returns the latest release tag. If its major.minor matches the requested version's major.minor, returns "main"; otherwise delegates to FetchLatestTagMatchingVersion.

```go
func FetchLatestTagMatchingOrMain(version string) (string, error)
```
Tokens:
Raw