### First-Time Spicetify Setup Workflow

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

A step-by-step guide for the initial setup of Spicetify, including configuring paths, setting a theme, backing up, and applying changes.

```bash
1. spicetify config spotify_path "..."
2. spicetify config prefs_path "..."
3. spicetify config current_theme "NordTheme"
4. spicetify backup
5. spicetify apply
6. Spotify restarts with customizations
```

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

### Full AdditionalOptions Configuration Example

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

An example demonstrating how to configure extensions, custom apps, and UI toggles within the [AdditionalOptions] section.

```ini
[AdditionalOptions]
extensions=extension1.js|extension2.js
custom_apps=my-app
sidebar_config=1
home_config=1
experimental_features=1
```

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

### Spicetify CLI Complete Setup Workflow

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

This outlines the sequence of commands for a full Spicetify installation. It involves reading configuration, detecting Spotify, validating paths, editing the configuration, creating a backup, and applying customizations.

```bash
1. utils.ParseConfig() → Read config
2. utils.FindAppPath() → Detect Spotify
3. cmd.InitPaths() → Validate paths
4. cmd.EditConfig() → Set theme
5. cmd.Backup() → Create backup
6. cmd.Apply() → Apply customizations
7. (Spotify restarts automatically)
```

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

### Full Spicetify Configuration File Example

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

An example of the complete Spicetify configuration file, showing various sections and settings.

```ini
[Setting]
spotify_path=/Applications/Spotify.app/Contents/Resources
prefs_path=/Users/user/Library/Application Support/Spotify/prefs
current_theme=NordTheme
color_scheme=original
inject_css=1
inject_theme_js=1
replace_colors=1
overwrite_assets=0
spotify_launch_flags=--no-update
always_enable_devtools=0
check_spicetify_update=1

[Backup]
version=2.5.0
with=1.2.57.1323

[Preprocesses]
disable_sentry=1
disable_ui_logging=1
remove_rtl_rule=1
expose_apis=1

[AdditionalOptions]
extensions=extension1.js|extension2.js|my-module.mjs
custom_apps=my-app|search-sidebar
sidebar_config=1
home_config=1
experimental_features=1

[Patch]
# Custom patches can be added here

```

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

### Setting Section Example

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

Example configuration for the [Setting] section, demonstrating various options for Spotify and theme customization. This includes paths, theme selection, and asset injection settings.

```ini
[Setting]
spotify_path=/Applications/Spotify.app/Contents/Resources
prefs_path=/Users/me/Library/Application Support/Spotify/prefs
current_theme=NordTheme
color_scheme=original
inject_css=1
inject_theme_js=1
replace_colors=1
overwrite_assets=0
spotify_launch_flags=--no-update|--enable-logging
always_enable_devtools=0
check_spicetify_update=1
```

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

### Start Spotify Backup

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

Creates a backup of Spotify's Apps folder. Copies all files from the Spotify installation, filtering out specified files. Preserves SPA files for restoration. Ensure paths are valid as no validation is performed. The destination directory is created if it doesn't exist.

```go
func Start(appPath, backupPath string) error {
    // Implementation details...
    return nil
}
```

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

### Start Backup

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

Creates a backup of Spotify's Apps folder. It copies all files from the Spotify installation, excluding specified files, and preserves SPA files for later restoration.

```APIDOC
## Start Backup

### Description
Creates a backup of Spotify's Apps folder. Copies all files from Spotify installation, filtering out certain files. Preserves SPA files (xpui.spa, login.spa, etc.) which are needed for restoration.

### Method
`Start(appPath, backupPath string) error`

### Parameters
#### Path Parameters
- **appPath** (string) - Required - Path to Spotify's Apps folder
- **backupPath** (string) - Required - Path to backup destination folder

### Returns
- `error` - nil if successful, error if backup fails

### Error Handling
- Returns error from Copy() if filesystem operation fails
- No validation of paths (caller responsible)
- Creates destination directory if missing
```

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

### Basic Preprocessing Example

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

Demonstrates basic preprocessing with specific flags enabled. Use this for standard preprocessing tasks.

```go
flags := preprocess.Flag{
    DisableSentry:  true,
    DisableLogging: true,
    RemoveRTL:      true,
    ExposeAPIs:     true,
    SpotifyVer:     "1.2.57.1323",
}

preprocess.Start(
    "2.5.0",
    "/path/to/Spotify",
    "/path/to/Extracted",
    flags,
)
```

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

### Config Usage Example

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

Demonstrates how to parse configuration, access a specific section, retrieve a value, and persist changes.

```go
cfg := utils.ParseConfig(configPath)
section := cfg.GetSection("Setting")
value := section.Key("spotify_path").String()
cfg.Write()
```

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

### Minimal Preprocessing Example

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

Illustrates minimal preprocessing, focusing only on exposing APIs. Use this when only API exposure is needed.

```go
flags := preprocess.Flag{
    DisableSentry:  false,
    DisableLogging: false,
    RemoveRTL:      false,
    ExposeAPIs:     true,  // Only expose APIs
    SpotifyVer:     "1.2.57",
}

preprocess.Start(version, spotifyPath, extractPath, flags)
```

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

### Applying Colors and CSS

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

This example shows how to apply custom colors and user CSS to a theme.

```APIDOC
## apply.UserCSS

### Description
Applies user-defined CSS and color schemes to the Spotify client.

### Method
`apply.UserCSS(spotifyAppsPath string, themePath string, colors map[string]string)`

### Parameters
#### Path Parameters
- `spotifyAppsPath` (string) - Path to the Spotify Apps directory.
- `themePath` (string) - Path to the theme directory.

#### Request Body
- `colors` (map[string]string) - A map where keys are color names (e.g., "main", "secondary") and values are their corresponding hex color codes.

### Request Example
```go
colors := map[string]string{
    "main":        "121212",
    "secondary":   "1db954",
    "tertiary":    "ffffff",
    "button":      "1ed760",
}

apply.UserCSS("/path/to/Spotify/Apps", "/path/to/NordTheme", colors)
```
```

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

### Color Struct Example

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

An example instantiation of the `Color` struct, showing the expected format for Hex (e.g., "1db954") and Decimal (e.g., "29,185,84").

```go
color := Color{
    Hex:     "1db954",
    Decimal: "29,185,84",
}
```

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

### Backup Section Example

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

Example configuration for the [Backup] section, showing metadata related to the last Spicetify backup. This section is managed by Spicetify commands and should not be edited manually.

```ini
[Backup]
version=2.5.0
with=1.2.57.1323
```

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

### Minimal Configuration

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

This example shows a minimal configuration for applying a theme, including essential flags and an empty color map.

```APIDOC
## apply.AdditionalOptions (Minimal)

### Description
Applies a theme with minimal configuration, disabling optional features.

### Method
`apply.AdditionalOptions(spotifyAppsPath string, flags Flag)`

### Parameters
#### Path Parameters
- `spotifyAppsPath` (string) - Path to the Spotify Apps directory.

#### Request Body
- `flags` (Flag) - A struct containing minimal theme application options:
  - `CurrentTheme` (string) - The name of the theme to apply.
  - `ColorScheme` (string) - The color scheme to use.
  - `InjectThemeJS` (bool) - Whether to inject theme JavaScript (set to false).
  - `Extension` ([]string) - An empty list of theme extension JavaScript files.
  - `CustomApp` ([]string) - An empty list of custom applications.
  - `SidebarConfig` (bool) - Whether to apply sidebar configuration (set to false).
  - `HomeConfig` (bool) - Whether to apply home configuration (set to false).
  - `ExpFeatures` (bool) - Whether to enable experimental features (set to false).
  - `SpicetifyVer` (string) - The Spicetify version to target.
  - `SpotifyVer` (string) - The Spotify version to target.

### Request Example
```go
flags := apply.Flag{
    CurrentTheme:    "MyTheme",
    ColorScheme:     "original",
    InjectThemeJS:   false,
    Extension:       []string{},
    CustomApp:       []string{},
    SidebarConfig:   false,
    HomeConfig:      false,
    ExpFeatures:     false,
    SpicetifyVer:    "2.5.0",
    SpotifyVer:      "1.2.57.1323",
}

apply.AdditionalOptions("/path/to/Spotify/Apps", flags)
```

## apply.UserCSS (Minimal)

### Description
Applies an empty user CSS, effectively disabling custom CSS overrides.

### Method
`apply.UserCSS(spotifyAppsPath string, themePath string, colors map[string]string)`

### Parameters
#### Path Parameters
- `spotifyAppsPath` (string) - Path to the Spotify Apps directory.
- `themePath` (string) - Path to the theme directory.

#### Request Body
- `colors` (map[string]string) - An empty map, indicating no custom colors are applied.

### Request Example
```go
colors := make(map[string]string)
apply.UserCSS("/path/to/Spotify/Apps", "", colors)
```
```

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

### Get Spotify Installation Path

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

Returns the cached absolute path to the Spotify installation directory. This path is determined after InitPaths has been called and typically points to the Spotify application folder containing the 'Apps' directory.

```go
func GetSpotifyPath() string
```

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

### Spicetify CLI Extension Installation Workflow

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

Procedure for installing extensions using Spicetify CLI. This involves loading configuration, adding the extension to the configuration list, validating paths, and refreshing the extensions to copy files.

```bash
1. cmd.InitConfig() → Load config
2. cmd.EditConfig() → Add extension to list
3. cmd.InitPaths() → Validate paths
4. cmd.RefreshExtensions() → Copy extension files
5. (Spotify auto-reloads)
```

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

### Install Lyrics Plus App

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

Run these commands in your terminal to install the Lyrics Plus custom app and apply the changes to your Spicetify client.

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

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

### Preprocesses Section Example

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

Example configuration for the [Preprocesses] section, which controls code transformation options applied during backup. These settings affect error reporting, UI logging, and API exposure.

```ini
[Preprocesses]
disable_sentry=1
disable_ui_logging=1
remove_rtl_rule=1
expose_apis=1
```

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

### Install Spicetify Extension

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

Initializes Spicetify configuration and paths, edits the configuration to include a new extension, and then refreshes the extensions. Use this to add custom extensions to Spicetify.

```go
cmd.InitConfig(false)
cmd.EditConfig([]string{"extensions", "myext.js"})
cmd.InitPaths()
cmd.InitSetting()
cmd.RefreshExtensions("myext.js")
```

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

### AppManifest JSON Example

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

Illustrates the JSON format for an AppManifest, showing how to list JavaScript files, extension files, and glob patterns for assets.

```json
{
    "files": [
        "lib/helper.js",
        "lib/util.js"
    ],
    "extension_files": [
        "hooks.js",
        "state-sync.js"
    ],
    "assets": [
        "images/**/*.png",
        "fonts/**/*",
        "styles/**/*.css"
    ]
}
```

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

### Applying Theme with Custom App

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

This example demonstrates how to apply a theme with custom application support, including injecting theme JS, checking for updates, and specifying extensions and custom apps.

```APIDOC
## apply.AdditionalOptions

### Description
Applies a theme with various configurations, including custom apps and extensions.

### Method
`apply.AdditionalOptions(spotifyAppsPath string, flags Flag)`

### Parameters
#### Path Parameters
- `spotifyAppsPath` (string) - Path to the Spotify Apps directory.

#### Request Body
- `flags` (Flag) - A struct containing various options for applying the theme:
  - `CurrentTheme` (string) - The name of the theme to apply.
  - `ColorScheme` (string) - The color scheme to use (e.g., "original").
  - `InjectThemeJS` (bool) - Whether to inject theme JavaScript.
  - `CheckSpicetifyUpdate` (bool) - Whether to check for Spicetify updates.
  - `Extension` ([]string) - A list of theme extension JavaScript files.
  - `CustomApp` ([]string) - A list of custom applications to enable.
  - `SidebarConfig` (bool) - Whether to apply sidebar configuration.
  - `HomeConfig` (bool) - Whether to apply home configuration.
  - `ExpFeatures` (bool) - Whether to enable experimental features.
  - `SpicetifyVer` (string) - The Spicetify version to target.
  - `SpotifyVer` (string) - The Spotify version to target.

### Request Example
```go
flags := apply.Flag{
    CurrentTheme:         "NordTheme",
    ColorScheme:          "original",
    InjectThemeJS:        true,
    CheckSpicetifyUpdate: true,
    Extension:            []string{"extension1.js"},
    CustomApp:            []string{"my-custom-app"},
    SidebarConfig:        true,
    HomeConfig:           true,
    ExpFeatures:          true,
    SpicetifyVer:         "2.5.0",
    SpotifyVer:           "1.2.57.1323",
}

apply.AdditionalOptions("/path/to/Spotify/Apps", flags)
```
```

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

### Windows Spotify Path

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

Specify the Spotify installation path on Windows using an absolute path.

```ini
spotify_path=C:\Users\YourUser\AppData\Roaming\Spotify
```

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

### Spotify Status Usage Example

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

Demonstrates how to use the `spotifystatus.Get` function to retrieve the status of Spotify apps and check if the status is `IsStock()`.

```go
status := spotifystatus.Get(appsFolder)
if status.IsStock() {
    // Ready for backup
}
```

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

### Spicetify Extension Development Workflow

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

Guide for developing extensions using Spicetify, involving configuration, live reloading with `watch`, and applying changes with `refresh`.

```bash
1. spicetify config extensions myext.js
2. spicetify watch -e
3. Edit extension file
4. Changes auto-reload
5. When done: spicetify refresh -e
```

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

### Find Spotify App Path

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

Detects the absolute path to the Spotify installation directory. Handles standard installers and Windows Store AppX packages on Windows, application bundles on macOS, and various locations including Flatpak on Linux. Returns an empty string if not found.

```go
func FindAppPath() string {
	// ... implementation details ...
}
```

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

### Copying Theme Assets

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

This example demonstrates how to copy theme assets from a theme directory to the Spotify Apps directory.

```APIDOC
## apply.UserAsset

### Description
Copies theme assets from a specified theme directory to the Spotify Apps directory.

### Method
`apply.UserAsset(spotifyAppsPath string, themePath string)`

### Parameters
#### Path Parameters
- `spotifyAppsPath` (string) - Path to the Spotify Apps directory.
- `themePath` (string) - Path to the theme directory containing assets.

### Request Example
```go
apply.UserAsset(
    "/path/to/Spotify/Apps",
    "/path/to/NordTheme",
)
```
```

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

### Example Modifier Function Usage

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

Demonstrates how to create and use a Modifier function to replace content within a file.

```go
modifier := func(content string) string {
    return strings.ReplaceAll(content, "old", "new")
}
utils.ModifyFile(filepath.Join(dest, "app.js"), modifier)
```

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

### Backup Workflow Diagram

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

Illustrates the steps involved in backing up Spicetify configurations, from starting the backup to extracting and preprocessing theme files.

```text
Apps/ [Spotify]
  ↓
backup.Start()  [Copy]
  ↓
Backup/ [Backup folder]
  ↓
backup.Extract()  [Unzip SPA]
  ↓
Extracted/Raw/  [Extracted code]
  ↓
preprocess.Start()  [Transform]
  ↓
Extracted/Themed/  [Processed]
  + Metadata (version, timestamp)
```

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

### Example Patch for Telemetry Removal

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

An example demonstrating how to create a Patch to remove telemetry data by replacing 'sendEvent' calls with 'undefined'. This patch is configured to be applied globally (not just once).

```go
Patch{
    Name: "Remove telemetry",
    Regex: `sendEvent\(([^)]+)\)`,
    Replacement: func(groups ...string) string {
        return "undefined"
    },
    Once: false,
}
```

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

### Linux Flatpak Spotify Paths

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

Specify Spotify installation and preferences paths when using Flatpak on Linux.

```ini
spotify_path=$HOME/.local/share/spotify-launcher/install/usr/share/spotify
prefs_path=$HOME/.config/spotify/prefs
```

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

### InitPaths

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

Validates and initializes paths to Spotify installation, preferences file, and app folders. Performs auto-detection if paths are not set in config. Exits if critical paths cannot be resolved.

```APIDOC
## InitPaths

### Description
Validates and initializes paths to Spotify installation, preferences file, and app folders. Performs auto-detection if paths are not set in config. Exits if critical paths cannot be resolved. Detects Windows Store edition (AppX) and configures appropriate app destination folder.

### Signature
```go
func InitPaths()
```

### Side Effects
- Updates global variables: `spotifyPath`, `prefsPath`, `appPath`, `appDestPath`, `isAppX`
- May auto-populate config file with detected paths
- Exits process if required paths cannot be found

### Exits
- When spotify_path is invalid
- When prefs_path cannot be found
- When Spotify is not installed or not properly initialized
```

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

### IsApplied

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

Checks if the Spotify installation is in the APPLIED state, meaning it has been fully customized by Spicetify and contains only extracted directories.

```APIDOC
## IsApplied

### Description
Checks if the Spotify installation is in the APPLIED state, meaning it has been fully customized by Spicetify and contains only extracted directories.

### Signature
```go
func (s status) IsApplied() bool
```

### Returns
`bool` - True only if Spotify is in APPLIED state.

### When True
- Spotify is fully customized by spicetify
- Has only extracted directories, no .spa files
- Can run: `spicetify refresh apply`
- Must restore to remove customizations

### When False
- Any other state

### Usage
```go
if spotifystatus.Get(appsFolder).IsApplied() {
    // Spotify is currently customized
    if userWantsToRestore() {
        cmd.Restore()
    }
}
```
```

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

### APPLIED State File Listing

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

Example file structure for the APPLIED state, showing extracted directories containing modified application code.

```text
Apps/
├── xpui/
│   ├── index.html
│   ├── xpui.js
│   └── ...
├── login/
│   └── ...
└── helper/
    └── ...
```

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

### Example Replacer Function Usage

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

Illustrates creating a Replacer function that conditionally wraps captured regex groups.

```go
replacer := func(submatches ...string) string {
    if len(submatches) > 1 {
        return "wrapped_" + submatches[1]
    }
    return submatches[0]
}
```

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

### GetSpotifyPath

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

Returns the cached Spotify installation path after InitPaths has been called. This is typically the Spotify application folder containing the Apps directory.

```APIDOC
## GetSpotifyPath

### Description
Returns the cached Spotify installation path after InitPaths has been called. This is typically the Spotify application folder containing the Apps directory.

### Signature
```go
func GetSpotifyPath() string
```

### Returns
- **string** - Absolute path to Spotify installation directory, e.g., `/Applications/Spotify.app/Contents/Resources` on macOS.
```

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

### Flag Struct

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

Configuration flags passed to Start() to control which preprocesses are applied during backup. These flags allow fine-grained control over transformations like Sentry removal, logging, RTL CSS rules, API exposure, and version-specific patching.

```APIDOC
## Flag Struct

### Description
Configuration flags passed to Start() to control which preprocesses are applied during backup.

### Fields
- **DisableSentry** (bool) - Remove Sentry (error reporting) and Qualaroo
- **DisableLogging** (bool) - Remove user interaction logging
- **RemoveRTL** (bool) - Remove Right-To-Left CSS rules
- **ExposeAPIs** (bool) - Expose Spotify internals to Spicetify
- **SpotifyVer** (string) - Spotify version for version-specific patches

### Source
`src/preprocess/preprocess.go:21-32`
```

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

### INI File Syntax Example

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

Illustrates the basic INI file format used by Spicetify, including sections and key-value pairs. Comments can be added using '#' or ';'.

```ini
[SectionName]
key1=value1
key2=value2

[AnotherSection]
key3=value3
```

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

### Start Preprocessing Function

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

The main function to initiate the preprocessing pipeline. It orchestrates CSS map loading, code patching, binary patching, and CSS processing.

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

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

### Initialize Spicetify Paths

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

Validates and initializes essential paths for Spicetify, including Spotify installation, preferences, and app folders. It attempts auto-detection if paths are not explicitly set and exits if critical paths cannot be resolved. This function updates global path variables and may auto-populate the config file.

```go
func InitPaths()
```

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

### Complete Backup and Apply Customizations

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

This Go program demonstrates the complete process of backing up Spotify, applying customizations, and restarting the application. It initializes configuration and paths, performs the backup, initializes theme settings, and then applies the customizations.

```go
package main

import (
    "github.com/spicetify/cli/src/backup"
    "github.com/spicetify/cli/src/cmd"
)

func main() {
    // Initialize
    cmd.InitConfig(false)
    cmd.InitPaths()
    
    // Backup
    cmd.Backup("2.5.0", false)
    
    // Initialize theme settings
    cmd.InitSetting()
    
    // Apply customizations
    cmd.Apply("2.5.0")
    
    // Spotify restarts automatically
}
```

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

### FindAppPath

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

Detects the absolute path to the Spotify installation directory on the current platform. It handles standard installations, Windows Store AppX packages, macOS applications, and Linux installations.

```APIDOC
## FindAppPath

### Description
Detects Spotify installation directory on current platform.

### Signature
```go
func FindAppPath() string
```

### Returns
`string` - Absolute path to Spotify installation, or empty string if not found

### Platform Specific Details

**Windows**
- `%APPDATA%\Spotify` (standard installer)
- Windows Store AppX package via PowerShell query

**macOS**
- `/Applications/Spotify.app/Contents/Resources`

**Linux**
- Results of `whereis spotify` command
- Potential locations: /opt/spotify/, /usr/share/spotify/, flatpak paths
- Validates Apps subfolder exists
```

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

### IsInvalid

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

Checks if the Spotify installation is in an INVALID state, typically due to a corrupted or missing installation, where the apps folder is empty.

```APIDOC
## IsInvalid

### Description
Checks if the Spotify installation is in an INVALID state, typically due to a corrupted or missing installation, where the apps folder is empty.

### Signature
```go
func (s status) IsInvalid() bool
```

### Returns
`bool` - True if Spotify is in INVALID state.

### When True
- Apps folder is empty (no .spa files, no directories)
- Indicates corruption or missing Spotify installation
- Cannot backup or apply
- Requires Spotify reinstallation

### Recovery Required
```go
if spotifystatus.Get(appsFolder).IsInvalid() {
    log.Println("Spotify installation corrupted")
    log.Println("Please reinstall Spotify")
}
```

### Causes
- Spotify installation incomplete/corrupted
- Apps folder deleted manually
- Permission issues preventing file detection
```

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

### Manual Backup and Extraction Operations

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

This Go program illustrates manual backup and extraction of Spotify application files. It shows how to create a backup, extract SPA files from the backup, and prepare them for preprocessing. Error handling for the backup process is included.

```go
package main

import (
    "log"
    "github.com/spicetify/cli/src/backup"
)

func main() {
    appPath := "/Applications/Spotify.app/Contents/Resources/Apps"
    backupPath := "/backup/location"
    extractPath := "/extract/location"
    
    // Create backup
    if err := backup.Start(appPath, backupPath); err != nil {
        log.Fatal("Backup failed:", err)
    }
    log.Println("Backup created")
    
    // Extract SPA files
    backup.Extract(backupPath, extractPath)
    log.Println("SPA files extracted")
    
    // Now can preprocess extracted files
}
```

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

### CSS Map Example

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

An example of a CSS map used to translate minified CSS class names to human-readable versions, enabling easier theme development.

```json
{
    "a": "main-container",
    "b": "header-top",
    "abc": "button-primary"
}
```

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

### Initialize and Apply Theme

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

Initializes Spicetify configuration and paths, then applies a theme and restarts Spotify. Use this to apply a theme to your Spotify client.

```go
cmd.InitConfig(false)
cmd.InitPaths()
cmd.InitSetting()
cmd.Apply("1.2.0")
cmd.SpotifyRestart()
```

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

### Orchestrate Backup with cmd.Backup()

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

The `cmd.Backup()` function orchestrates the entire backup process, including checking Spotify status, creating backup files, extracting SPA files, preprocessing them, and storing metadata. It takes version and silent flags as parameters.

```go
func Backup(version string, silent bool) {
    // 1. Check Spotify is backupable
    status := spotifystatus.Get(appPath)
    
    // 2. Create backup files
    backup.Start(appPath, backupFolder)
    
    // 3. Extract SPA files
    backup.Extract(backupFolder, rawFolder)
    
    // 4. Preprocess extracted files
    preprocess.Start(version, spotifyPath, extractedPath, flags)
    
    // 5. Store backup metadata
    backupSection.Key("version").SetValue(version)
}

```

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

### Normal Workflow: Spicetify Backup

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

Illustrates the steps involved when a user runs 'spicetify backup'. This includes extracting SPA files, preprocessing code, and copying them to the Apps folder, resulting in the APPLIED state.

```text
┌─────┐
│STOCK│  User: spicetify backup
└──┬──┘
   │
   ├─→ Extract SPA files
   │
   ├─→ Preprocess code
   │
   └──→ Copy to Apps folder
        │
        └──→ ┌────────┐
             │APPLIED │
             └────┬───┘
                  │
                  │ User: spicetify refresh
                  │ (update CSS/JS)
                  │
                  └──→ (stays APPLIED)
```

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

### Minimal Configuration Apply

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

Applies a minimal theme configuration with default settings for extensions, custom apps, and feature flags. Also applies an empty user CSS configuration.

```go
flags := apply.Flag{
    CurrentTheme:    "MyTheme",
    ColorScheme:     "original",
    InjectThemeJS:   false,
    Extension:       []string{},
    CustomApp:       []string{},
    SidebarConfig:   false,
    HomeConfig:      false,
    ExpFeatures:     false,
    SpicetifyVer:    "2.5.0",
    SpotifyVer:      "1.2.57.1323",
}

apply.AdditionalOptions("/path/to/Spotify/Apps", flags)

colors := make(map[string]string)
apply.UserCSS("/path/to/Spotify/Apps", "", colors)
```

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

### Create Directory if Not Exists

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

Ensures a directory exists, creating it and any necessary parent directories with user-only read/write/execute permissions (0700). It's a no-op if the directory already exists and panics on critical errors.

```go
func CheckExistAndCreate(dir string)
```

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

### INVALID State File Listing

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

Example file structure for the INVALID state, represented by an empty Apps directory.

```text
Apps/
(empty directory)
```

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

### Development Build Preprocessing

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

Shows how to configure preprocessing for a development build, keeping RTL rules enabled for testing purposes.

```go
flags := preprocess.Flag{
    DisableSentry:  true,
    DisableLogging: true,
    RemoveRTL:      false,  // Keep RTL for testing
    ExposeAPIs:     true,
    SpotifyVer:     "1.2.57",
}

preprocess.Start("Dev", spotifyPath, extractPath, flags)
```

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

### Converting Config to Preprocess Flags

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

Demonstrates how to read configuration values from an INI file and convert them into the `preprocess.Flag` struct.

```go
flags := preprocess.Flag{
    DisableSentry:  cfg.GetSection("Preprocesses").Key("disable_sentry").MustBool(true),
    DisableLogging: cfg.GetSection("Preprocesses").Key("disable_ui_logging").MustBool(true),
    RemoveRTL:      cfg.GetSection("Preprocesses").Key("remove_rtl_rule").MustBool(true),
    ExposeAPIs:     cfg.GetSection("Preprocesses").Key("expose_apis").MustBool(true),
    SpotifyVer:     detectedVersion,
}
```

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

### Print Config Path

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

Use these commands to display the current Spicetify configuration file path.

```bash
spicetify -c
spicetify --config
```

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

### Build Spicetify CLI on Windows

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

Build the Spicetify executable on Windows. Ensure you are in the 'cli' directory after cloning the repository.

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

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

### Get Spicetify Executable Directory

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

Returns the directory where the Spicetify executable is located. Useful for finding related files or resources.

```go
func GetExecutableDir() string {
	// Implementation details omitted for brevity
}
```

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

### Spicetify Backup Workflow Steps

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

Outlines the sequential steps in the cmd.Backup() workflow. This process involves copying application files, extracting SPA archives, preprocessing the extracted code, and storing backup metadata.

```text
1. Copy Apps folder
   backup.Start(appPath, backupFolder)
   → Copies SPA files and other content to Backup/

2. Extract SPA files
   backup.Extract(backupFolder, rawExtractFolder)
   → Unzips xpui.spa and login.spa to Raw/xpui/ and Raw/login/

3. Preprocess
   preprocess.Start(...)
   → Transforms extracted code
   → Creates Themed/ with color variations

4. Store metadata
   → Writes backup version to config

```

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

### IsStock

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

Checks if the Spotify installation is in the original STOCK state, meaning only original .spa files are present and no Spicetify customizations have been applied.

```APIDOC
## IsStock

### Description
Checks if the Spotify installation is in the original STOCK state, meaning only original .spa files are present and no Spicetify customizations have been applied.

### Signature
```go
func (s status) IsStock() bool
```

### Returns
`bool` - True only if Spotify is in STOCK state.

### When True
- Spotify has only original .spa files
- Directory structure shows .spa files only
- No spicetify customizations applied
- Ready for first-time backup

### When False
- Any other state (INVALID, APPLIED, MIXED)

### Usage
```go
if spotifystatus.Get(appsFolder).IsStock() {
    log.Println("Ready for spicetify setup")
}
```
```

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

### Create Manual Backup in Go

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

Use this function to manually create a backup of Spotify application files. It first copies the Apps folder and then extracts the SPA files. Ensure the provided paths for application, backup, and raw extraction are correct.

```go
import (
    "github.com/spicetify/cli/src/backup"
    "github.com/spicetify/cli/src/utils"
)

appPath := "/path/to/Spotify/Apps"
backupPath := "/path/to/backup/Backup"
rawPath := "/path/to/backup/Extracted/Raw"

// Step 1: Copy Apps folder
if err := backup.Start(appPath, backupPath); err != nil {
    log.Fatal(err)
}

// Step 2: Extract SPA files
backup.Extract(backupPath, rawPath)

// At this point:
// - SPA files are in backupPath/
// - Extracted directories are in rawPath/

```

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

### Spicetify Custom App Development Workflow

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

Instructions for developing custom applications with Spicetify, including setting up the app directory, configuring Spicetify, and using `watch` and `refresh`.

```bash
1. Create CustomApps/my-app/
2. spicetify config custom_apps my-app
3. spicetify watch -a
4. Edit app files
5. Changes auto-reload
6. When done: spicetify refresh -a
```

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

### IsModdable

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

Checks if the Spotify installation can be modified with Spicetify customizations. This is true for APPLIED or MIXED states, meaning Spicetify files have been extracted or applied.

```APIDOC
## IsModdable

### Description
Checks if the Spotify installation can be modified with Spicetify customizations. This is true for APPLIED or MIXED states, meaning Spicetify files have been extracted or applied.

### Signature
```go
func (s status) IsModdable() bool
```

### Returns
`bool` - True if Spotify is in APPLIED or MIXED state.

### When True
- Spotify has extracted/modified files
- Safe to run: `spicetify apply refresh`
- Can inject customizations

### When False
- Spotify is in STOCK state (original)
- Spotify is in INVALID state (corrupted)
- Cannot modify; must backup first

### Usage
```go
if spotifystatus.Get(appsFolder).IsModdable() {
    // Can apply customizations
}
```
```

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

### IsBackupable

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

Checks if the Spotify installation is in a state where it can be backed up. This is true for STOCK or MIXED states, indicating that the original Spotify files are present and can be preserved.

```APIDOC
## IsBackupable

### Description
Checks if the Spotify installation is in a state where it can be backed up. This is true for STOCK or MIXED states, indicating that the original Spotify files are present and can be preserved.

### Signature
```go
func (s status) IsBackupable() bool
```

### Returns
`bool` - True if Spotify is in STOCK or MIXED state.

### When True
- Spotify is in original or mixed state
- Safe to run: `spicetify backup`
- Backup will preserve original SPA files

### When False
- Spotify is in APPLIED state (already customized)
- Spotify is in INVALID state (corrupted)
- Cannot backup; must restore first if modified

### Usage
```go
if spotifystatus.Get(appsFolder).IsBackupable() {
    // Safe to backup
}
```
```

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

### Initialize Theme Settings

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

Reads and validates theme configuration, including CSS and JavaScript injection, color schemes, and asset overwriting. It attempts to load color configurations and disables settings for missing theme resources.

```go
func InitSetting()
```

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

### InitConfig

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

Initializes the global configuration by reading and parsing the config-xpui.ini file. This must be called before other config-dependent operations.

```APIDOC
## InitConfig

### Description
Initializes the global configuration by reading and parsing the config-xpui.ini file. This must be called before other config-dependent operations. Populates global configuration sections including Setting, Backup, Preprocesses, AdditionalOptions, and Patch sections.

### Signature
```go
func InitConfig(isQuiet bool)
```

### Parameters
#### Query Parameters
- **isQuiet** (bool) - Optional - Whether to suppress output

### Returns
None. Sets global variables: `cfg`, `settingSection`, `backupSection`, `preprocSection`, `featureSection`, `patchSection`.
```

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

### STOCK State File Listing

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

Example file structure representing the STOCK state, where original .spa files are present in the Apps directory.

```text
Apps/
├── xpui.spa
├── login.spa
└── helper.spa
```

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

### View All Spicetify Settings

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

Prints all current Spicetify configuration settings to the console. Useful for a complete overview.

```bash
spicetify config
```

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

### Get Spicetify User Data Folder

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

Retrieves the platform-specific path to the Spicetify user data directory. This is where user configurations and data are stored.

```go
func GetSpicetifyFolder() string {
	// Implementation details omitted for brevity
}
```

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

### Configure Extensions and Custom Apps

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

Use this to specify which extensions and custom apps to load. Extensions are loaded from Spicetify or executable directories, while custom apps are loaded from CustomApps/ folders.

```ini
extensions=extension1.js|extension2.js|my-module.mjs
```

```ini
custom_apps=my-app|another-app
```

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

### Get Spicetify State Folder

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

Returns the path to a subfolder within the state management directory. It can create necessary subdirectories like Backup or Extracted.

```go
func GetStateFolder(subfolder string) string {
	// Implementation details omitted for brevity
}
```

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

### Get JavaScript Helper Directory

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

Provides the path to the directory containing built-in JavaScript helper files. These scripts are used for various Spicetify functionalities.

```go
func GetJsHelperDir() string {
	// Implementation details omitted for brevity
}
```

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

### CheckExistAndCreate

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

Checks if a directory exists and creates it with all parent directories if it doesn't. Uses permission mode 0700.

```APIDOC
## CheckExistAndCreate

### Description
Checks if a directory exists and creates it with all parent directories if it doesn't. Uses permission mode 0700 (user rwx only).

### Method
(Function Call)

### Parameters
#### Path Parameters
- **dir** (string) - Required - Directory path to create

### Behavior
- No-op if directory exists
- Creates directory and parents with mkdir -p semantics if missing
- Panics on unrecoverable errors
```

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

### MIXED State File Listing

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

Example file structure for the MIXED state, indicating an incomplete operation where both original .spa files and extracted directories coexist.

```text
Apps/
├── xpui.spa       ← Original
├── login.spa      ← Original
├── xpui/          ← Extracted
│   ├── index.html
│   └── ...
└── login/         ← Extracted
    └── ...
```

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

### Enable Configuration UIs

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

Toggles for enabling user interface customization for the sidebar and home page. Also includes a toggle for experimental features.

```ini
sidebar_config=1
```

```ini
home_config=1
```

```ini
experimental_features=1
```

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

### Check if Spotify is in Stock State

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

Use IsStock to verify if Spotify has only original .spa files and no Spicetify customizations have been applied. This is the state ready for initial setup.

```Go
if spotifystatus.Get(appsFolder).IsStock() {
    log.Println("Ready for spicetify setup")
}
```

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

### Command Orchestration and Configuration

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

Functions for initializing configuration and paths, applying customizations, managing backups, refreshing themes/extensions/apps, and editing configuration settings.

```APIDOC
## Package: api-reference-cmd

### Description
Provides functions for command orchestration, configuration management, and user interaction within the Spicetify CLI.

### Functions
- `InitConfig()`: Initializes the Spicetify configuration.
- `InitPaths()`: Initializes the file paths used by Spicetify.
- `InitSetting()`: Initializes a specific Spicetify setting.
- `Apply()`: Applies Spicetify customizations.
- `Backup()`: Creates a backup of Spicetify configurations.
- `Restore()`: Restores Spicetify configurations from a backup.
- `RefreshTheme()`: Refreshes the current Spicetify theme.
- `RefreshExtensions()`: Refreshes Spicetify extensions.
- `RefreshApps()`: Refreshes Spicetify applications.
- `EditConfig()`: Edits the Spicetify configuration file.
- `EditColor()`: Edits color settings in the Spicetify configuration.
- `Watch()`: Watches for changes in configuration files and applies them.
- `Auto()`: Automatically applies Spicetify configurations.
```

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

### Create STOCK State for Testing

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

Use this bash command to set the Spotify Apps directory to a 'STOCK' state, ensuring only .spa files are present. This is useful for testing scenarios where Spicetify expects to apply its changes.

```bash
cd /path/to/Spotify/Apps
rm -rf xpui login helper  # Remove directories
ls  # Should show only .spa files
```

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

### Conditional Backup Logic

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

Check if a backup is possible before proceeding. This snippet handles cases where Spotify might be modified or corrupted, guiding the user to restore or reinstall.

```go
status := spotifystatus.Get(appsFolder)

if !status.IsBackupable() {
    if status.IsApplied() {
        log.Println("Spotify is modified. Restore first: spicetify restore")
    } else if status.IsInvalid() {
        log.Println("Spotify is corrupted. Reinstall Spotify.")
    }
    return
}

cmd.Backup(version, false)
```

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

### Backup Spotify Application Files

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

Creates a backup of Spotify's application files before modifications. It preprocesses SPA files and stores them along with metadata. Use this before applying any Spicetify themes or customizations.

```go
func Backup(spicetifyVersion string, silent bool)
```

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

### IsMixed

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

Checks if the Spotify installation is in a MIXED state, indicating a combination of original .spa files and extracted directories, often due to an interrupted operation or Spotify update.

```APIDOC
## IsMixed

### Description
Checks if the Spotify installation is in a MIXED state, indicating a combination of original .spa files and extracted directories, often due to an interrupted operation or Spotify update.

### Signature
```go
func (s status) IsMixed() bool
```

### Returns
`bool` - True only if Spotify is in MIXED state.

### When True
- Spotify has both original .spa files and extracted directories
- Indicates incomplete operation or recent Spotify update
- Not stable; should be resolved

### Causes
- User interrupted backup/restore operation
- Spotify updated during spicetify backup/restore
- Previous version crashed during apply

### Recovery
```go
if spotifystatus.Get(appsFolder).IsMixed() {
    // Recover by:
    cmd.Restore()     // Back to STOCK, then
    cmd.Backup()      // Create new backup
    cmd.Apply()       // Re-apply customizations
}
```
```

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

### Backup Workflow Preprocessing Steps

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

Illustrates the preprocessing stage within the larger backup workflow. This section highlights where preprocessing begins and ends in the sequence of operations.

```text
1. Copy Spotify Apps folder to backup
2. Extract SPA files
3. ← Start preprocess here
4. Apply patches and CSS mapping
5. Create themed variations
6. ← Finish preprocess here
7. Store backup metadata
```

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

### Spinner

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

Provides a global spinner object for progress indication, leveraging the pterm library. It offers methods to start, stop, and display various status messages for the spinner.

```APIDOC
## Spinner

### Description
Global spinner object for progress indication, integrated from the pterm library.

### Usage
```go
spinner, _ := utils.Spinner.Start("Loading...")
// Do work
spinner.Success("Done")
```

### Methods
- `Start(text)`: Begins the spinner with the provided text.
- `Success(text)`: Finishes the spinner with a success message.
- `Warning(text)`: Finishes the spinner with a warning message.
- `Fail(text)`: Finishes the spinner with an error message.
- `Info(text)`: Finishes the spinner with an informational message.
```

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

### Execute Spicetify CLI

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

Run the compiled Spicetify executable. Use './spicetify' for Linux/macOS and './spicetify.exe' for Windows.

```bash
./spicetify
./spicetify.exe
```

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

### Get Custom App Path

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

Finds the directory for a custom Spicetify app. It searches within the user's CustomApps folder and the executable directory. Requires an 'index.js' file.

```go
func GetCustomAppPath(appName string) (string, error) {
	// Implementation details omitted for brevity
}
```

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

### ParseConfig Function

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

Loads and parses an INI configuration file. If the file does not exist, it creates a default configuration with auto-detected Spotify paths and ensures all required sections and keys are present, adding missing entries with default values.

```go
func ParseConfig(configPath string) Config
```