The basic idea behind Spotify's new Save to Spotify tool is a two-step process. First, something generates an audio file - a text-to-speech service, an AI agent, a script, anything. Second, the Save to Spotify CLI takes that file and deposits it into the user's private Spotify library as a podcast episode. The tool handles only the second step. It does not create audio. It moves audio into Spotify.

That distinction matters because the announcement framing - AI agents "generating and saving" personal podcasts - implies a single seamless action. In practice, audio generation and audio uploading are separate operations that need to be chained together, either manually or through an agent that orchestrates both.

Spotify announced the beta on May 7, 2026. The tool is not a consumer-facing button inside the Spotify app. It is an open-source, Go-based command-line binary that AI coding agents - specifically Claude Code, OpenAI Codex, and Cursor - can invoke as part of a larger workflow. Content saved through the tool is private, visible only to the account holder, and sits alongside existing subscriptions and saved episodes in the Spotify library. According to Spotify, that library is accessible across more than 2,000 devices, so the portability extends to anything saved through the CLI without additional configuration.

This guide covers the two-step workflow, installation, authentication, upload commands, advanced options, and the technical constraints worth knowing before building an automated pipeline.

Step 1: Generate the audio file

Save to Spotify accepts audio files in four formats: .mp3, .m4a, .wav, and .ogg. That file must exist before the CLI can do anything. Common ways to produce it include:

  • Text-to-speech services such as ElevenLabs or Microsoft's edge-tts
  • The macOS built-in say command for quick local generation
  • Any other TTS or audio generation tool that outputs a supported format

An AI agent like Claude Code can orchestrate this entire chain. Given a prompt - summarize today's calendar, brief me on three news stories, recap this week's meeting notes - the agent writes a script, calls a TTS service to convert the text to audio, saves the file locally, then passes it to save-to-spotify upload. The CLI is the last step in that chain, not the whole chain.

Step 2: Upload the file to Spotify

Once the audio file exists, the CLI takes over. It creates a podcast show inside the user's Spotify library if one does not already exist, uploads the file as an episode, and sets any metadata provided. A single command handles show creation, file upload, and episode metadata together.

The tool is published under the Apache-2.0 license, with 309 stars and 13 forks on GitHub as of the May 7 launch week. Five contributors have worked on the repository, which shows 16 commits across 16 branches - the most recent bug fix merged three days after the initial commit.

Installation

According to Spotify, the quickest installation method is a curl-bash script hosted at https://saveto.spotify.com/install.sh. Running the following command in a terminal fetches and executes the installer:

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

The installer places the binary on the system PATH and, by default, also installs agent skills - configuration files that expose the tool to compatible agents. Skills land in agent-specific directories. For Claude Code the target is ~/.claude/skills/save-to-spotify/. For Cursor, it is ~/.cursor/skills/save-to-spotify/. Agents that read .agents/skills/ directories will also pick them up automatically.

To pin to a specific version rather than pulling the latest, the installer accepts a --version flag:

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

Version 0.1.1 is the current stable release. To install the binary to a non-standard directory, pass --dir:

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

If the agent skill directories are not wanted - for example, in a CI environment where only the binary is needed - pass --no-skills to skip that step entirely.

Alternative installation methods

For environments where running a remote shell script is not acceptable, Spotify provides several other routes.

The skills.sh package manager supports a single command:

npx skills add spotify/save-to-spotify

For Claude Code specifically, the tool is listed on the Claude Code plugin marketplace under the name spotify/save-to-spotify. Inside a Claude Code session, running /plugin marketplace add spotify/save-to-spotify performs the installation. A second command, /plugin install save-to-spotify@save-to-spotify, installs it from the plugin registry directly.

For OpenClaw workspaces, the tool is listed on ClawHub as @spotify/save-to-spotify. The ClawHub install command is:

openclaw skills install @spotify/save-to-spotify

According to the repository README, the ClawHub listing installs the agent skill. If the save-to-spotify binary is not already on the system PATH, the curl-bash installer still needs to run separately.

Manual installation

If none of the above methods work, pre-built binaries are available on the GitHub releases page. The manual process involves four steps. First, download save-to-spotify-{os}-{arch}-v{version}.zip and its matching .sha256 file from the releases page. Second, verify integrity:

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

Third, unzip the archive. The contents include the binary and a skills/save-to-spotify/ directory tree. Fourth, move the binary to a directory on the PATH and mark it executable:

sudo mv save-to-spotify /usr/local/bin/
chmod +x /usr/local/bin/save-to-spotify

Building from source

The tool requires Go 1.21 or later. To build from source:

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

The tool requires a one-time authentication step that opens a browser. According to Spotify, the login command is:

save-to-spotify auth login

This opens a browser window prompting the user to authorize the CLI through a Spotify account. After authorization, the CLI stores a token at ~/.config/save-to-spotify/token.json (or under $XDG_CONFIG_HOME if that environment variable is set). Token refresh is automatic from that point forward.

The default authentication model uses DPoP-bound tokens. This creates a second file, dpop_key.json, in the same directory. Both files must be present for automatic token refresh to work. If dpop_key.json is missing, refresh attempts will fail with an invalid_request error. In CI and headless environments, both files need to be persisted between runs.

For remote servers and SSH sessions where opening a browser is not possible, a headless login mode is available:

save-to-spotify auth login --no-browser

This prints a URL to open on any device. After authorization on that device, the user pastes the redirect URL back into the terminal. From that point, automatic refresh handles everything - agents cannot complete this step alone, but after initial authentication they operate without human intervention.

To check whether authentication is still valid, run:

save-to-spotify auth status

This command exits non-zero if the token is expired, making it suitable as a CI pre-flight health check. The environment variable SAVE_TO_SPOTIFY_AUTH_TOKEN overrides the stored token entirely, which is useful for fully non-interactive pipelines that manage tokens externally. Note that this override disables automatic refresh.

Uploading audio: the core workflow

The upload command is the primary entrypoint for agents. According to the repository documentation, a single command handles show creation, file upload, and episode metadata together. The basic syntax is:

save-to-spotify upload <file> --title <title>

For example:

save-to-spotify upload ./recap.mp3 --title "Monday Standup Recap"

If no show exists yet, the CLI creates one automatically. If a show already exists from a previous run, it reuses the most recently created show. This default behavior suits daily briefing pipelines where all episodes belong to a single ongoing show.

Organizing into separate shows

For users who want to separate content by topic - for instance, keeping daily briefings distinct from language practice sessions - the --new-show flag creates a named show and saves the episode into it:

save-to-spotify upload ./lecture.mp3 --title "CS 101 - Lecture Notes Week 6" --new-show "Lecture Notes"

To target a specific existing show, use --show-id with a Spotify show URI:

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

Adding metadata

The upload command accepts optional metadata flags. --summary adds an episode description. --image attaches a cover image in .jpg or .png format, up to 1 MB. --language sets the language code, defaulting to en:

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

Managing shows and episodes separately

Beyond the upload shortcut, the tool exposes granular commands for shows and episodes.

Shows

To list all existing shows:

save-to-spotify shows

To create a show explicitly before uploading:

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

To retrieve show details by ID:

save-to-spotify shows get <id>

To delete a show and all its episodes:

save-to-spotify shows delete <id>

According to the documentation, shows serve as containers. A single show can hold all content, or multiple shows can organize content by topic. The structuring choice has no effect on playback - episodes from any show appear in the user's Spotify library.

Episodes

The episodes create command mirrors upload but provides more explicit control:

save-to-spotify episodes create --title "Sprint Review Notes" --file ./review.mp3

After an episode is uploaded, it enters a processing queue. The episodes status command checks readiness:

save-to-spotify episodes status <episode-id>

The --wait flag polls until the episode becomes READY, with a default timeout of five minutes:

save-to-spotify episodes status <episode-id> --wait

According to the documentation, most episodes are ready within a few minutes. Polling every 20 seconds is the recommended interval. Episodes must be in READY status before timeline items can be set.

To delete a specific episode:

save-to-spotify episodes delete <episode-id>

One of the more technically detailed features is the timeline system. Timelines add chapter markers and companion content to saved episodes, displayed in Spotify's in-player interface during playback.

Timeline data is supplied as a JSON file. An example structure:

{
  "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 } }
  ]
}

The timeline command sets all items at once, replacing any existing timeline:

save-to-spotify timeline set --episode-id <episode-id> --from-file timeline.json

There are several structural rules worth noting. If chapters are used at all, there must be at least two, and the first must start at start_time_ms: 0. Images in the timeline require a positive duration_ms. Links require a positive duration_ms and a valid HTTPS URL. spotify_entity items require a full spotify:... URI; duration_ms is optional but must be positive when set. Companion items - images, links, and Spotify entities - must not overlap in time. The only exception: a link and a spotify_entity may share the same chapter segment, as long as their time windows do not overlap.

According to the documentation, spotify_entity is the preferred type whenever the destination already exists on Spotify - a track, an album, a podcast episode. Full spotify:... URIs are preferred over bare IDs or open.spotify.com URLs.

To retrieve an existing timeline:

save-to-spotify timeline get <episode-id>

To delete all timeline items from an episode:

save-to-spotify timeline delete <episode-id>

Agent integration and JSON output

All commands support a --json flag that outputs structured JSON instead of human-readable text. This mode is designed for agents that need to parse results programmatically:

save-to-spotify --json upload ./recap.mp3 --title "Standup Recap" | jq -r .episode_uri

When errors occur in JSON mode, the response takes the form {"error": "message"}. According to the documentation, the typical agent workflow runs in this sequence: check auth status, list existing shows, create or reuse a show, upload the audio file, poll episode status until READY, then set timeline items if needed.

A global --timeout flag overrides the default 30-second API request timeout. The value accepts duration strings like 1m or 90s. The same timeout is configurable via the SAVE_TO_SPOTIFY_TIMEOUT environment variable.

Environment variables

The tool supports five environment variables for headless and CI configuration:

  • SAVE_TO_SPOTIFY_AUTH_TOKEN - overrides the stored Bearer token; disables auto-refresh
  • SAVE_TO_SPOTIFY_BACKEND_URL - overrides the backend API URL (default: https://saveto.spotify.com)
  • SAVE_TO_SPOTIFY_TIMEOUT - sets the API request timeout
  • SAVE_TO_SPOTIFY_CLIENT_ID - overrides the built-in OAuth client ID
  • SAVE_TO_SPOTIFY_NO_UPDATE_CHECK - disables passive update checks

Context: where this fits in Spotify's agent strategy

The Save to Spotify launch follows a pattern Spotify has been building since early 2026. In April 2026, Spotify connected its personalization engine to Claude, enabling Free and Premium users to request playlists and podcast recommendations through conversation. That integration placed Spotify as a content source inside an AI interface. The Save to Spotify CLI inverts that relationship: the AI agent becomes a content creator, and Spotify becomes the destination.

Both moves reflect the same structural logic. Spotify is not building the intelligence layer. It is building authenticated, stable endpoints that agents can reach. The Spotify video distribution API that went live for five hosting platforms in May 2026 follows the same pattern: open the infrastructure, let partners and agents do the creative and editorial work.

For the marketing and media community, the CLI raises a practical question about content format. Personal Podcasts created through this tool are private - there is no RSS feed, no public distribution, no advertising inventory. They exist only within a single user's account. That makes them irrelevant as a direct advertising surface. What they represent, instead, is a shift in how audio fits into agentic workflows: not as a broadcast medium but as a personal, on-demand output format tied to individual data sources like calendars, inboxes, and reading lists.

According to Spotify, the feature is in beta. The repository shows rapid iteration - the initial commit landed roughly one week before the May 7 announcement, with multiple bug fixes merged in the days that followed.

Timeline

Summary

Who: Spotify, the audio streaming platform, with the Save to Spotify CLI tool targeting developers and users of AI coding agents including Claude Code, OpenAI Codex, and Cursor.

What: A beta, open-source command-line interface tool that allows AI agents to upload audio files and save them as private podcast episodes - called Personal Podcasts - directly to a user's Spotify library. The tool handles show creation, file upload, episode metadata, and optional chapter timelines. It supports .mp3, .m4a, .wav, and .ogg formats and is written in Go (93.5% of the codebase).

When: Announced on May 7, 2026. Version 0.1.1 is the current stable release. The repository had 309 stars and 13 forks at the time of the announcement.

Where: The CLI binary is distributed via https://saveto.spotify.com/install.sh and listed on the Claude Code plugin marketplace, ClawHub, and the Skills.sh registry. The source code is available on GitHub under the Apache-2.0 license. The generated content lands in the user's Spotify library, accessible across more than 2,000 Spotify-compatible devices.

Why: Spotify is positioning itself as a distribution endpoint for AI-generated audio content. As agentic workflows become more common in tools like Claude Code and OpenAI Codex, the company is extending its library infrastructure to capture that output - audio briefings, lecture summaries, travel itineraries, meeting recaps - as private listening content inside its existing ecosystem. The move follows Spotify's April 2026 integration with Claude and reflects a broader strategy of opening authenticated infrastructure to the agent layer rather than building intelligence in-house.

Share this article
The link has been copied!