feat: add AppleScript engine for direct macOS Spotify control

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.1.1 - Unreleased
 
+- Add `applescript` engine for direct Spotify.app control on macOS (thanks @adam91holt)
 - CI: bump golangci-lint-action to support golangci-lint v2
 
 ## 0.1.0 - 2026-01-02

README.md

@@ -65,7 +65,7 @@ Global flags:
 - `--market <cc>` market country code
 - `--language <tag>` language/locale (default `en`)
 - `--device <name|id>` target device
-- `--engine <auto|web|connect>` API engine (default `connect`)
+- `--engine <auto|web|connect|applescript>` API engine (default `connect`, `applescript` is macOS-only)
 - `--json` / `--plain`
 - `--no-color`
 - `-q, --quiet` / `-v, --verbose` / `-d, --debug`

docs/spec.md

@@ -1,4 +1,4 @@
-# spogo CLI spec (v0.1.0)
+# spogo CLI spec (v0.1.1)
 
 One-liner: Spotify power CLI using web cookies; search + playback control.
 Parser: Kong.
@@ -29,7 +29,7 @@ spogo [global flags] <command> [args]
 - `--market <cc>` default: account market or `US`
 - `--language <tag>` default: `en`
 - `--device <name|id>` default: active device
-- `--engine <auto|web|connect>` default: `connect`
+- `--engine <auto|web|connect|applescript>` default: `connect` (`applescript` is macOS-only)
 - `--no-input`
 
 ## Commands

internal/app/context.go

@@ -175,8 +175,29 @@ func (c *Context) Spotify() (spotify.API, error) {
 		}
 		c.spotifyClient = client
 		return client, nil
+	case "applescript":
+		var fallback spotify.API
+		if webClient, webErr := spotify.NewClient(spotify.Options{
+			TokenProvider: spotify.CookieTokenProvider{
+				Source: source,
+			},
+			Market:   c.Profile.Market,
+			Language: c.Profile.Language,
+			Device:   c.Profile.Device,
+			Timeout:  c.Settings.Timeout,
+		}); webErr == nil {
+			fallback = webClient
+		}
+		client, err := spotify.NewAppleScriptClient(spotify.AppleScriptOptions{
+			Fallback: fallback,
+		})
+		if err != nil {
+			return nil, err
+		}
+		c.spotifyClient = client
+		return client, nil
 	default:
-		return nil, fmt.Errorf("unknown engine %q (use auto, web, or connect)", engine)
+		return nil, fmt.Errorf("unknown engine %q (use auto, web, connect, or applescript)", engine)
 	}
 }
 

internal/app/context_applescript_test.go

@@ -0,0 +1,22 @@
+//go:build !darwin
+
+package app
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/steipete/spogo/internal/config"
+)
+
+func TestSpotifyAppleScriptEngine_NonDarwin(t *testing.T) {
+	t.Parallel()
+
+	ctx := &Context{Profile: config.Profile{CookiePath: "/tmp/cookies.json", Engine: "applescript"}}
+	if _, err := ctx.Spotify(); err == nil || !strings.Contains(err.Error(), "only available on macOS") {
+		t.Fatalf("expected macOS-only error, got: %v", err)
+	}
+	if ctx.spotifyClient != nil {
+		t.Fatalf("expected no cached client on error")
+	}
+}

internal/cli/cli.go

@@ -10,7 +10,7 @@ import (
 	"github.com/steipete/spogo/internal/output"
 )
 
-const Version = "0.1.0"
+const Version = "0.1.1"
 
 func New() *CLI {
 	return &CLI{}
@@ -50,7 +50,7 @@ type Globals struct {
 	Market   string           `help:"Market country code." env:"SPOGO_MARKET"`
 	Language string           `help:"Language/locale." env:"SPOGO_LANGUAGE"`
 	Device   string           `help:"Device name or id." env:"SPOGO_DEVICE"`
-	Engine   string           `help:"Engine (auto|web|connect)." env:"SPOGO_ENGINE"`
+	Engine   string           `help:"Engine (auto|web|connect|applescript)." env:"SPOGO_ENGINE"`
 	JSON     bool             `help:"JSON output." env:"SPOGO_JSON"`
 	Plain    bool             `help:"Plain output." env:"SPOGO_PLAIN"`
 	NoColor  bool             `help:"Disable color output." env:"SPOGO_NO_COLOR"`