Sun to Spotify

Turn any topic, question, or feed into a dialogue podcast — and listen to it in Spotify or your favorite podcast app.

Just say:

What’s the latest in voice and audio AI? Give me a 10-minute roundup.

What’s happening in the stock market this morning? Make it a 5-minute brief.

Give me my daily brief based on my calendar for the next 30 minutes.

Summarize The Hard Thing About Hard Things as a 20-minute podcast.

How should I think about marketing my B2B startup? Give me a 15-minute deep dive.

Sun handles everything: research, script writing, multi-speaker dialogue, audio mixing, and publishing. The result lands in your Spotify library, ready to play from any device.

---

Quick Start

1. Install the CLI

Prompt your agent to install the CLI:

Install the Sun CLI by running https://sunapp-ai.github.io/sun-to-spotify/install.sh

Or install manually:

curl -fsSL https://sunapp-ai.github.io/sun-to-spotify/install.sh | bash

The installer picks the first available Python package manager — uv (preferred), then pipx, then pip --user — and installs sun-cli from PyPI. Python 3.10+ required.

uv tool install 'sun-cli>=0.2.1'   # manual: places sun at ~/.local/bin/sun
pipx install 'sun-cli>=0.2.1'      # isolated venv
pip  install 'sun-cli>=0.2.1'      # standard install

2. Install the skill

The sun-to-spotify skill teaches Claude Code how to drive the CLI. Drop it into your Claude Code skills directory:

# Project-scoped (only available inside this repo)
git clone https://github.com/sunapp-ai/sun-to-spotify .claude/skills/sun-to-spotify

# User-scoped (available in every project)
git clone https://github.com/sunapp-ai/sun-to-spotify ~/.claude/skills/sun-to-spotify

Claude Code picks up the skill on the next session.

3. Authenticate

sun login

Opens your browser to sign in or create a free account. One-time for typical use — the CLI caches credentials; tokens refresh automatically. For CI or headless hosts, set SUN_TOKEN or copy credentials from a machine where you ran sun login once (see references/cli-usage.md).

sun whoami    # check who's logged in
sun logout    # forget cached session

4. Ask for whatever you want to hear

The skill handles generation, polling, and download automatically — login, job creation, status checks, and saving the manifest plus per-segment MP3s locally.

5. Save to Spotify

When generation finishes, the skill can offer to publish your podcast to Spotify. Install the save-to-spotify skill or CLI. That path is upload-only (Sun already produced the audio); for richer Spotify packaging (cover art, in-player timeline, and so on), use save-to-spotify directly.

---

Personal API tokens

sun tokens create     # mint a token (name: ^[a-z0-9-]+$, 1-64 chars)
sun tokens list
sun tokens revoke 

The full secret is printed once at creation. Token shape: sk_live__.

---

CLI reference

sun courses ... still works as a hidden alias for backwards compatibility — it prints a one-line deprecation warning on stderr. Use sun audio in new scripts.

audio create flags

audio get

sun audio get                        # manifest JSON to stdout
sun audio get  --out ./dir           # overview.json + cover. + episodes/NNN-.mp3
sun audio get  --partial --out ./dir # works mid-generation; fills in episodes as they finish

Signed segment URLs are re-signed on each fetch — do not cache audio_url values long-term.

JSON mode

Every command supports --json for scripting. Errors emit {"error": {"code": "...", "message": "..."}} and a non-zero exit. See references/cli-usage.md for exit codes and troubleshooting.

---

Environment variables

---

Error codes (quick)

Read error.code, not only HTTP status (409 covers multiple cases).

---

Repository layout

• SKILL.md — skill entry point for Claude Code
• references/cli-usage.md — full CLI reference
• references/http-api.md — HTTP API when you are not using the CLI
• install.sh — curl installer (hosted via GitHub Pages)

---

Links

• Sun
• Genesis Prompt Format Arena benchmark
• sun-cli on PyPI
• Claude Code
• Save to Spotify