Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
S

save-to-spotify

> 编程语言
Open source

Command line interface to save your personal media to Spotify.

389 stars0 likes2 views
WebsiteGitHub

About

Command line interface to save your personal media 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.

What you can make

Point your agent at content you have, and get a finished episode on Spotify:

  • Morning briefing — your calendar, tasks, and overnight repo activity as a 3-minute daily brief
  • Deep dive — turn a topic, article, or PDF into a personalized audio explainer
  • Meeting recap — drop in a transcript, get a 2-minute summary with action items
  • Travel guide — a private audio itinerary for your next trip
  • News roundup — a daily roundup from the newsletters, feeds, and sites you follow
  • Bedtime story — a custom story using your kid's name and favorite setting

Describe what you want in plain English; the agent sources, scripts, narrates, and saves it.

Making the audio

This CLI saves audio to Spotify — it does not generate speech itself. You bring a voice engine:

  • Kokoro (recommended) — free, local, no API key, no limits (~340 MB)
  • OpenAI TTS — high quality, needs OPENAI_API_KEY
  • ElevenLabs — most natural, needs ELEVENLABS_API_KEY

No key? Kokoro is the default. Already have an OpenAI or ElevenLabs key? The agent detects it and offers to use it — no extra setup.

Run save-to-spotify tts status to see what's available, or save-to-spotify tts add to register any other engine.

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:

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

Common options:

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

# 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

Skills.sh

Install the agent skill to Claude Code, Cursor, Codex, and 50+ other agents:

bash
npx skills add spotify/save-to-spotify

ClawHub / OpenClaw

Save to Spotify is listed on ClawHub as @spotify/save-to-spotify. Install it into your active OpenClaw workspace:

bash
openclaw skills install @spotify/save-to-spotify

The ClawHub listing installs the agent skill. The skill uses the save-to-spotify CLI, so if the binary is not already on your PATH, run the curl-bash installer above.

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:
    bash
    shasum -c save-to-spotify-darwin-arm64-v0.2.0.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 (not needed on Windows).
  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/.

Windows notes

  • Run the install script in Git Bash (ships with Git for Windows); it installs save-to-spotify.exe to ~/.local/bin and offers a PATH fix.
  • The Windows binaries are not code-signed yet: SmartScreen may block the first run. Unblock with right-click → Properties → Unblock, or Unblock-File save-to-spotify.exe in PowerShell.

Build from source

Requires Go 1.21+.

bash
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.

bash
# 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). If you use DPoP-bound tokens (the default), the sibling dpop_key.json is also required. For CI and headless environments, see the CI / Automation guide.

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.

bash
save-to-spotify upload  --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.

…

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").

bash
# 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 

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

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.

…

episodes create flags:

Flag Description
--title Episode title (required)
--file Media file path (required)
--show-id Target show ID or URI (default: most recent show)
--summary Episode description
--image Cover image file (.jpg/.png, max 1 MB)
--language Language code

timeline

Add chapter markers and in-player companion content to saved episodes. A timeline can include chapters, images, external links, and Spotify-native references via spotify_entity. Prefer spotify_entity whenever the thing you want listeners to open already exists on Spotify, prefer full spotify:... URIs over bare IDs or open.spotify.com URLs, and note that a link and a spotify_entity can both appear in the same timeline when both destinations are useful.

bash
# Get timeline items for an episode
save-to-spotify timeline get 

# Set (replace all) timeline items from a JSON file
save-to-spotify timeline set --episode-id  --from-file timeline.json

# Delete all timeline items
save-to-spotify timeline delete 

Example timeline.json:

json
{
  "items": [
    { "chapter": { "title": "Introduction", "start_time_ms": 0 } },
    { "chapter": { "title": "Key Concepts", "start_time_ms": 45000 } },
    { "spotify_entity": { "start_time_ms": 60000, "duration_ms": 30000, "uri": "spotify:track:abc123" } },
    { "link": { "start_time_ms": 95000, "duration_ms": 20000, "url": "https://example.com/slides" } },
    { "chapter": { "title": "Summary", "start_time_ms": 120000 } }
  ]
}

Timeline rules:

  • chapter: optional, but if present there must be at least 2; the first must start at 0.
  • image: requires a positive duration_ms and a local .jpg/.png file path or an image_token.
  • link: requires a positive duration_ms and an HTTP(S) URL.
  • spotify_entity: requires a full spotify:... URI; duration_ms is optional but must be positive when set.
  • Companion items (image, link, spotify_entity) must not overlap in time, but a link and a spotify_entity may share the same segment/chapter as long as their windows do not overlap.

list

Alternative command for listing your content.

bash
# List episodes for the most recent show
save-to-spotify list

# List episodes for a specific show
save-to-spotify list episodes --show-id spotify:show:abc123

# List all shows
save-to-spotify list shows

Other commands

Command Description
update Check for and install CLI updates
token Print access token to stdout (for piping to curl, etc.)
version Print version and commit hash

Global flags

Flag Description
--json Output results as JSON (for scripting and automation)
--timeout API request timeout (default: 30s, e.g. 1m, 90s)

Documentation

  • Agent integration — JSON mode, typical workflow, error handling
  • CI / Automation — GitHub Actions setup, headless auth, credential persistence

Environment variables

Variable Purpose Default
SAVE_TO_SPOTIFY_AUTH_TOKEN Bearer token override (expires in ~1 hour, no auto-refresh — see CI guide) —
SAVE_TO_SPOTIFY_BACKEND_URL Override the backend API URL https://saveto.spotify.com
SAVE_TO_SPOTIFY_TIMEOUT API request timeout (e.g. 30s, 2m) 30s
SAVE_TO_SPOTIFY_CLIENT_ID OAuth client ID override built-in
SAVE_TO_SPOTIFY_NO_UPDATE_CHECK Disable passive update checks off
SAVE_TO_SPOTIFY_HEADERS Additional headers for backend requests (JSON object of header name/value pairs; only X-STS-* headers are accepted) —

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Go

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言