### Initialize and run a spinner

Source: https://github.com/theckman/yacspin/blob/master/README.md

Configure and start a basic spinner instance. Error handling is omitted for brevity.

```go
cfg := yacspin.Config{
	Frequency:       100 * time.Millisecond,
	CharSet:         yacspin.CharSets[59],
	Suffix:          " backing up database to S3",
	SuffixAutoColon: true,
	Message:         "exporting data",
	StopCharacter:   "✓",
	StopColors:      []string{"fgGreen"},
}

spinner, err := yacspin.New(cfg)
// handle the error

err = spinner.Start()

// doing some work
time.Sleep(2 * time.Second)

spinner.Message("uploading data")

// upload...
time.Sleep(2 * time.Second)

err = spinner.Stop()
```

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

### Start and Stop Spinner

Source: https://context7.com/theckman/yacspin/llms.txt

Shows how to start spinner animation and stop it with either a success or failure state. The Stop() and StopFail() methods use configured characters and messages.

```go
package main

import (
	"fmt"
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency:         100 * time.Millisecond,
		CharSet:           yacspin.CharSets[59], // dots animation
		Suffix:            " backing up database",
		SuffixAutoColon:   true,
		Message:           "exporting data",
		StopCharacter:     "✓",
		StopColors:        []string{"fgGreen"},
		StopMessage:       "backup complete",
		StopFailCharacter: "✗",
		StopFailColors:    []string{"fgRed"},
		StopFailMessage:   "backup failed",
	}

	spinner, _ := yacspin.New(cfg)

	// Start the spinner animation
	if err := spinner.Start(); err != nil {
		fmt.Printf("failed to start spinner: %v\n", err)
		return
	}

	// Simulate work
	time.Sleep(3 * time.Second)

	// Stop with success message
	if err := spinner.Stop(); err != nil {
		fmt.Printf("failed to stop spinner: %v\n", err)
	}
	// Output: ✓ backing up database: backup complete

	// Or stop with failure message using:
	// spinner.StopFail()
	// Output: ✗ backing up database: backup failed
}
```

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

### Install yacspin package

Source: https://github.com/theckman/yacspin/blob/master/README.md

Use this command to add the yacspin dependency to your Go project.

```bash
go get github.com/theckman/yacspin
```

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

### Write Spinner Output to Custom Writer

Source: https://context7.com/theckman/yacspin/llms.txt

Configure the spinner to write its output to a custom `io.Writer`, such as a `bytes.Buffer` for in-memory capture or `os.Stderr` for alternate console output. This example demonstrates writing to a buffer and then to stderr.

```go
package main

import (
	"bytes"
	"os"
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	// Write to a custom buffer
	var buf bytes.Buffer

	cfg := yacspin.Config{
		Frequency:    100 * time.Millisecond,
		CharSet:      yacspin.CharSets[26], // Simple dots: ., .., ...
		Suffix:       " working",
		Writer:       &buf, // Custom writer
		TerminalMode: yacspin.ForceNoTTYMode | yacspin.ForceDumbTerminalMode,
	}

	spinner, _ := yacspin.New(cfg)
	spinner.Start()

	spinner.Message("step 1")
	time.Sleep(100 * time.Millisecond)
	spinner.Message("step 2")

	spinner.Stop()

	// Write to stderr instead of stdout
	cfgStderr := yacspin.Config{
		Frequency: 100 * time.Millisecond,
		CharSet:   yacspin.CharSets[11],
		Suffix:    " processing",
		Writer:    os.Stderr,
	}

	spinnerErr, _ := yacspin.New(cfgStderr)
	spinnerErr.Start()
	time.Sleep(2 * time.Second)
	spinnerErr.Stop()
}
```

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

### Create Spinner with Configuration

Source: https://context7.com/theckman/yacspin/llms.txt

Demonstrates creating a new spinner instance using a Config struct. Customize animation frequency, character set, colors, and stop messages.

```go
package main

import (
	"fmt"
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency:         100 * time.Millisecond,
		CharSet:           yacspin.CharSets[11], // braille dots spinner
		Suffix:            " ",
		SuffixAutoColon:   true,
		Message:           "processing data",
		ColorAll:          true,
		Colors:            []string{"fgYellow"},
		StopCharacter:     "✓",
		StopColors:        []string{"fgGreen"},
		StopMessage:       "completed successfully",
		StopFailCharacter: "✗",
		StopFailColors:    []string{"fgRed"},
		StopFailMessage:   "operation failed",
	}

	spinner, err := yacspin.New(cfg)
	if err != nil {
		fmt.Printf("failed to create spinner: %v\n", err)
		return
	}

	// Spinner is ready to use
	_ = spinner
}
```

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

### Pause and Unpause Spinner for Atomic Updates

Source: https://context7.com/theckman/yacspin/llms.txt

Use `Pause()` and `Unpause()` to make multiple configuration changes atomically without rendering partial updates. This is useful when updating several properties at once.

```go
package main

import (
	time "time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency:       100 * time.Millisecond,
		CharSet:         yacspin.CharSets[11],
		Suffix:          " initializing",
		SuffixAutoColon: true,
		Message:         "loading configuration",
		Colors:          []string{"fgCyan"},
		StopCharacter:   "✓",
		StopColors:      []string{"fgGreen"},
	}

	spinner, _ := yacspin.New(cfg)
	spinner.Start()

	time.Sleep(2 * time.Second)

	// Pause to make atomic updates
	if err := spinner.Pause(); err != nil {
		return
	}

	// Update multiple properties while paused
	spinner.Suffix(" processing")
	spinner.Message("analyzing data")
	spinner.Colors("fgYellow")

	// Resume animation with all changes applied at once
	if err := spinner.Unpause(); err != nil {
		return
	}

	time.Sleep(2 * time.Second)
	spinner.Stop()
}
```

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

### Render Spinner at End of Line

Source: https://context7.com/theckman/yacspin/llms.txt

Set SpinnerAtEnd to true in the configuration to display the animation after the message text.

```go
package main

import (
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency:     100 * time.Millisecond,
		CharSet:       yacspin.CharSets[11],
		SpinnerAtEnd:  true,
		Prefix:        " ", // Add space before spinner when at end
		Message:       "Processing data",
		StopCharacter: "✓",
		StopColors:    []string{"fgGreen"},
	}

	spinner, _ := yacspin.New(cfg)
	spinner.Start()
	// Output: Processing data ⣾

	time.Sleep(3 * time.Second)

	spinner.StopMessage("Done!")
	spinner.Stop()
	// Output: Done! ✓
}
```

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

### Update Prefix and Suffix Dynamically

Source: https://context7.com/theckman/yacspin/llms.txt

Use Prefix() and Suffix() methods to change text during execution. SuffixAutoColon automatically inserts a colon between the suffix and message.

```go
package main

import (
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency:       100 * time.Millisecond,
		CharSet:         yacspin.CharSets[11],
		Prefix:          "[Task 1] ",
		Suffix:          " downloading",
		SuffixAutoColon: true,
		Message:         "file1.zip",
		StopCharacter:   "✓",
	}

	spinner, _ := yacspin.New(cfg)
	spinner.Start()
	// Output: [Task 1] ⣾ downloading: file1.zip

	time.Sleep(2 * time.Second)

	// Update prefix and suffix dynamically
	spinner.Prefix("[Task 2] ")
	spinner.Suffix(" uploading")
	spinner.Message("file2.zip")
	// Output: [Task 2] ⣾ uploading: file2.zip

	time.Sleep(2 * time.Second)
	spinner.Stop()
}
```

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

### Configure Terminal Mode

Source: https://context7.com/theckman/yacspin/llms.txt

Use TerminalMode to control animation behavior, including forcing TTY/non-TTY modes or manual stepping.

```go
package main

import (
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	// Auto-detect terminal capabilities (default)
	cfgAuto := yacspin.Config{
		Frequency:    100 * time.Millisecond,
		CharSet:      yacspin.CharSets[11],
		TerminalMode: yacspin.AutomaticMode,
	}

	// Force TTY mode with smart terminal (ANSI escape codes)
	cfgTTY := yacspin.Config{
		Frequency:    100 * time.Millisecond,
		CharSet:      yacspin.CharSets[11],
		TerminalMode: yacspin.ForceTTYMode | yacspin.ForceSmartTerminalMode,
	}

	// Force non-TTY mode (each update on new line, no animation)
	cfgNoTTY := yacspin.Config{
		Frequency:    100 * time.Millisecond,
		CharSet:      yacspin.CharSets[11],
		TerminalMode: yacspin.ForceNoTTYMode | yacspin.ForceDumbTerminalMode,
	}

	// Manual stepping mode: animate only on Message() calls
	// Useful for log files or controlled output
	cfgManual := yacspin.Config{
		Frequency:    100 * time.Millisecond,
		CharSet:      yacspin.CharSets[11],
		TerminalMode: yacspin.ForceNoTTYMode | yacspin.ForceSmartTerminalMode,
	}

	spinner, _ := yacspin.New(cfgManual)
	spinner.Start()

	// In manual mode, each Message() call triggers an animation step on a new line
	spinner.Message("Step 1")
	time.Sleep(500 * time.Millisecond)
	spinner.Message("Step 2")
	time.Sleep(500 * time.Millisecond)
	spinner.Message("Step 3")

	spinner.Stop()

	_ = cfgAuto
	_ = cfgTTY
	_ = cfgNoTTY
}
```

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

### Update Spinner Message Dynamically

Source: https://context7.com/theckman/yacspin/llms.txt

Illustrates updating the spinner's message in real-time using the Message() method. This allows for live progress updates during long-running operations.

```go
package main

import (
	"fmt"
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency:       100 * time.Millisecond,
		CharSet:         yacspin.CharSets[11],
		Suffix:          " uploading files",
		SuffixAutoColon: true,
		StopCharacter:   "✓",
		StopColors:      []string{"fgGreen"},
	}

	spinner, _ := yacspin.New(cfg)
	spinner.Start()

	// Simulate uploading multiple files with live updates
	files := []string{"document.pdf", "image.png", "data.csv", "report.xlsx"}
	for i, file := range files {
		spinner.Message(fmt.Sprintf("(%d/%d) %s", i+1, len(files), file))
		time.Sleep(500 * time.Millisecond)
	}

	spinner.StopMessage("all files uploaded")
	spinner.Stop()
}
```

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

### Handle OS Signals for Graceful Exit

Source: https://context7.com/theckman/yacspin/llms.txt

Set up a signal handler to catch OS interrupts (like Ctrl+C) and ensure the spinner stops cleanly, restoring the terminal cursor. This is crucial for preventing a hidden cursor on program exit.

```go
package main

import (
	"fmt"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency:         100 * time.Millisecond,
		CharSet:           yacspin.CharSets[11],
		Suffix:            " ",
		SuffixAutoColon:   true,
		Message:           "processing",
		StopCharacter:     "✓",
		StopColors:        []string{"fgGreen"},
		StopFailCharacter: "✗",
		StopFailColors:    []string{"fgRed"},
	}

	spinner, err := yacspin.New(cfg)
	if err != nil {
		fmt.Printf("failed to create spinner: %v\n", err)
		os.Exit(1)
	}

	// Set up signal handler to restore cursor on interrupt
	sigCh := make(chan os.Signal, 1)
	signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)

	go func() {
		<-sigCh
		spinner.StopFailMessage("interrupted by user")
		_ = spinner.StopFail() // Restores cursor
		os.Exit(0)
	}()

	if err := spinner.Start(); err != nil {
		fmt.Printf("failed to start: %v\n", err)
		os.Exit(1)
	}

	// Simulate long-running work (Ctrl+C to test interrupt handling)
	time.Sleep(30 * time.Second)

	if err := spinner.Stop(); err != nil {
		fmt.Printf("failed to stop: %v\n", err)
		os.Exit(1)
	}
}
```

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

### Configure Spinner Colors

Source: https://context7.com/theckman/yacspin/llms.txt

Use `Colors()`, `StopColors()`, and `StopFailColors()` to set ANSI colors for the spinner animation and stop states. The `ColorAll` config option controls whether colors apply to the entire line or just the spinner character.

```go
package main

import (
	time "time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency: 100 * time.Millisecond,
		CharSet:   yacspin.CharSets[14],
		Suffix:    " processing",
		ColorAll:  true, // Color the entire line, not just the spinner
	}

	spinner, _ := yacspin.New(cfg)

	// Set spinner colors (can combine multiple attributes)
	spinner.Colors("fgHiCyan", "bold")

	// Set success state colors
	spinner.StopColors("fgGreen", "bold")
	spinner.StopCharacter("✓")
	spinner.StopMessage("success")

	// Set failure state colors
	spinner.StopFailColors("fgRed", "bold")
	spinner.StopFailCharacter("✗")
	spinner.StopFailMessage("failed")

	spinner.Start()
	time.Sleep(2 * time.Second)
	spinner.Stop()
}

// Valid colors include:
// Basic: black, red, green, yellow, blue, magenta, cyan, white
// Foreground: fgBlack, fgRed, fgGreen, fgYellow, fgBlue, fgMagenta, fgCyan, fgWhite
// Hi-Intensity: fgHiBlack, fgHiRed, fgHiGreen, fgHiYellow, fgHiBlue, fgHiMagenta, fgHiCyan, fgHiWhite
// Background: bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite
// Attributes: bold, faint, italic, underline, blinkslow, blinkrapid, reversevideo, concealed, crossedout
```

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

### Check Spinner Status

Source: https://context7.com/theckman/yacspin/llms.txt

The Status() method returns the current state, which can be compared against constants like SpinnerRunning or SpinnerPaused.

```go
package main

import (
	"fmt"
	"time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency: 100 * time.Millisecond,
		CharSet:   yacspin.CharSets[11],
		Suffix:    " working",
	}

	spinner, _ := yacspin.New(cfg)

	fmt.Printf("Status: %s\n", spinner.Status()) // Status: stopped

	spinner.Start()
	fmt.Printf("Status: %s\n", spinner.Status()) // Status: running

	spinner.Pause()
	fmt.Printf("Status: %s\n", spinner.Status()) // Status: paused

	spinner.Unpause()
	fmt.Printf("Status: %s\n", spinner.Status()) // Status: running

	// Check status programmatically
	if spinner.Status() == yacspin.SpinnerRunning {
		fmt.Println("Spinner is currently running")
	}

	spinner.Stop()
	fmt.Printf("Status: %s\n", spinner.Status()) // Status: stopped
}

// Available SpinnerStatus values:
// yacspin.SpinnerStopped
// yacspin.SpinnerStarting
// yacspin.SpinnerRunning
// yacspin.SpinnerStopping
// yacspin.SpinnerPausing
// yacspin.SpinnerPaused
// yacspin.SpinnerUnpausing
```

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

### List Valid Colors for Yacspin

Source: https://context7.com/theckman/yacspin/llms.txt

Iterate through the `yacspin.ValidColors` map to retrieve and print all available color names that can be used in spinner configurations. This provides a reference for foreground, background, and text attribute colors.

```go
package main

import (
	"fmt"

	"github.com/theckman/yacspin"
)

func main() {
	// Print all valid color names
	fmt.Println("Valid colors for yacspin:")
	for color := range yacspin.ValidColors {
		fmt.Printf("  %s\n", color)
	}

	// Categories of valid colors:
	// Basic colors: black, red, green, yellow, blue, magenta, cyan, white
	// Foreground: fgBlack, fgRed, fgGreen, fgYellow, fgBlue, fgMagenta, fgCyan, fgWhite
	// Foreground Hi-Intensity: fgHiBlack, fgHiRed, fgHiGreen, fgHiYellow, fgHiBlue, fgHiMagenta, fgHiCyan, fgHiWhite
	// Background: bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite
	// Background Hi-Intensity: bgHiBlack, bgHiRed, bgHiGreen, bgHiYellow, bgHiBlue, bgHiMagenta, bgHiCyan, bgHiWhite
	// Text attributes: reset, bold, faint, italic, underline, blinkslow, blinkrapid, reversevideo, concealed, crossedout
}
```

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

### Update Spinner Animation Frequency

Source: https://context7.com/theckman/yacspin/llms.txt

The `Frequency()` method changes how often the spinner animation updates. Different character sets may look better at different speeds. The duration must be greater than 0.

```go
package main

import (
	time "time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency: 200 * time.Millisecond, // Initial: slower animation
		CharSet:   yacspin.CharSets[14],
		Suffix:    " processing",
	}

	spinner, _ := yacspin.New(cfg)
	spinner.Start()

	time.Sleep(2 * time.Second)

	// Speed up the animation
	if err := spinner.Frequency(50 * time.Millisecond); err != nil {
		// Handle error - duration must be > 0
	}

	time.Sleep(2 * time.Second)

	// Slow it back down
	spinner.Frequency(150 * time.Millisecond)

	time.Sleep(2 * time.Second)
	spinner.Stop()
}
```

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

### Change Spinner Character Sets

Source: https://context7.com/theckman/yacspin/llms.txt

Use `CharSet()` to change spinner animation characters at runtime. The library provides 91 built-in character sets (indices 0-90) in `yacspin.CharSets`, or you can provide custom character slices. The `Reverse()` method can reverse the animation direction.

```go
package main

import (
	time "time"

	"github.com/theckman/yacspin"
)

func main() {
	cfg := yacspin.Config{
		Frequency: 100 * time.Millisecond,
		CharSet:   yacspin.CharSets[9], // Classic: |, /, -, \
		Suffix:    " working",
	}

	spinner, _ := yacspin.New(cfg)
	spinner.Start()

	time.Sleep(2 * time.Second)

	// Switch to braille dots animation
	spinner.CharSet(yacspin.CharSets[11]) // ⣾, ⣽, ⣻, ⢿, ⡿, ⣟, ⣯, ⣷

	time.Sleep(2 * time.Second)

	// Use custom character set
	spinner.CharSet([]string{"🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"})

	time.Sleep(2 * time.Second)

	// Reverse the animation direction
	spinner.Reverse()

	time.Sleep(2 * time.Second)
	spinner.Stop()
}

// Popular built-in CharSets:
// CharSets[9]:  |, /, -, \  (classic)
// CharSets[11]: ⣾, ⣽, ⣻, ⢿, ⡿, ⣟, ⣯, ⣷ (braille)
// CharSets[14]: ⠋, ⠙, ⠹, ⠸, ⠼, ⠴, ⠦, ⠧, ⠇, ⠏ (dots)
// CharSets[37]: 🕐 through 🕛 (clock emojis)
// CharSets[39]: 🌍, 🌎, 🌏 (earth)
// CharSets[70]: 🌑 through 🌘 (moon phases)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.