save-to-spotify

Save to Spotify

A command-line tool for saving audio content to Spotify. Built for agents and automation — generate a daily briefing, language lesson, or meeting recap, then push it to Spotify where it's available alongside your other listening.

Quick Start

Prompt your agent to install:

> Install Save to Spotify by running https://saveto.spotify.com/install.sh

Installs the CLI and exposes the skill to Claude Code, Cursor, Codex, and any agent that reads .agents/skills/.

Once installed, invoke with /save-to-spotify (Claude Code) or $save-to-spotify (Codex), or just describe what you want in plain English.

Install

Curl-bash

Same script the Quick Start prompt runs:

curl -fsSL https://saveto.spotify.com/install.sh | bash

Common options:

# Pin a specific version
curl -fsSL https://saveto.spotify.com/install.sh | bash -s -- --version 0.1.1

# Custom install directory
curl -fsSL https://saveto.spotify.com/install.sh | bash -s -- --dir ~/.local/bin

# Binary only — skip the agent skill
curl -fsSL https://saveto.spotify.com/install.sh | bash -s -- --no-skills

Claude Code plugin marketplace

/plugin marketplace add spotify/save-to-spotify
/plugin install save-to-spotify@save-to-spotify

Manual

If you can't run the install script:

1. Download save-to-spotify-{os}-{arch}-v{version}.zip and its matching .sha256 from the releases page.
2. Verify integrity:

   shasum -c save-to-spotify-darwin-arm64-v0.1.1.zip.sha256
   

3. Unzip — you get the binary plus a skills/save-to-spotify/ tree.
4. Move the binary to a directory on your PATH and chmod +x it.
5. (Optional) Copy skills/save-to-spotify/ into your agent's skill directory, e.g. ~/.claude/skills/save-to-spotify/ or ~/.cursor/skills/save-to-spotify/.

Build from source

Requires Go 1.21+.

go build -ldflags "-X github.com/spotify/save-to-spotify/cmd.commit=$(git rev-parse --short HEAD)" \
  -o save-to-spotify .
sudo mv save-to-spotify /usr/local/bin/

Authentication

Log in once — the CLI stores your token and refreshes it automatically.

# Opens your browser to authorize (default)
save-to-spotify auth login

# Headless mode — prints a URL to open on any device, then you paste back the redirect URL
# Useful for SSH sessions and remote servers
save-to-spotify auth login --no-browser

# Check if you're logged in
save-to-spotify auth status

# Log out (removes stored credentials)
save-to-spotify auth logout

Tokens are stored in ~/.config/save-to-spotify/token.json (using $XDG_CONFIG_HOME if set).

Commands

upload

The primary command. Uploads a media file and creates an episode in one step. This is the main entrypoint for agents — a single command handles show creation, file upload, and episode metadata.

save-to-spotify upload <file> --title <title> [flags]

Flag	Description
--title	Episode title (required)
--show-id	Target show ID or URI
--new-show	Create a new show with this title and save the file to it
--summary	Episode description
--image	Cover image file (.jpg/.png, max 1 MB)
--language	Language code (default: en)

If --show-id or --new-show is not specified, the CLI will use your most recently created show, or create a new one if none exists.

# Save an audio file to Spotify — uses your most recent show (or creates one automatically)
save-to-spotify upload ./recap.mp3 --title "Monday Standup Recap"

# Save to a specific show
save-to-spotify upload ./lesson.mp3 --title "Spanish Lesson 12" --show-id spotify:show:abc123

# Organize saved items into separate shows
save-to-spotify upload ./lecture.mp3 --title "CS 101 — Lecture Notes Week 6" --new-show "Lecture Notes"

# With cover image and description
save-to-spotify upload ./briefing.mp3 \
  --title "Morning Briefing" \
  --summary "Weather and calendar for today" \
  --image ./cover.jpg

Supported formats: .mp3, .m4a, .wav, .ogg.

shows

Shows are containers for your saved content. You can use a single show for everything or create separate shows to organize by topic (e.g. "Daily Briefings", "Language Practice", "Meeting Recaps").

# List your shows
save-to-spotify shows

# Create a show
save-to-spotify shows create --title "Lecture Notes" --summary "Audio summaries of CS 101 lectures"

# Get show details
save-to-spotify shows get <id>

# Delete a show and all its episodes
save-to-spotify shows delete <id>

shows create flags:

Flag	Description
--title	Show title (required)
--summary	Show description (default: "(no description)")
--image	Cover image file (.jpg/.png, max 1 MB)
--language	Language code (default: en)

episodes

Each saved file becomes an episode within a show.