Command-line interface

SpotifyScraper ships a spotifyscraper command that prints any entity as JSON and downloads cover art or preview clips — handy for shell pipelines, quick lookups, and feeding jq.

Install

The CLI lives behind the cli extra (it pulls in Typer):

pip install "spotifyscraper[cli]"

Want media tagging too (for download preview --embed-cover)? Add the media extra:

pip install "spotifyscraper[cli,media]"

Verify the install:

spotifyscraper --version
spotifyscraper --help

Pass --no-hint before the command to suppress the one-time star hint for that invocation.

Entity commands

Each entity type has a command that accepts a Spotify URL, URI, or bare 22-character ID and writes the entity's to_dict() as JSON to stdout:

Command	Fetches
spotifyscraper track <id>	a Track
spotifyscraper album <id>	an Album with its tracks
spotifyscraper artist <id>	an Artist
spotifyscraper playlist <id>	a Playlist
spotifyscraper episode <id>	an Episode
spotifyscraper show <id>	a Show with its episodes

spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC
spotifyscraper album "https://open.spotify.com/album/..."
spotifyscraper artist spotify:artist:0gxyHStUsqpMadRV0Di1Qt

Pretty printing and files

By default the JSON is compact (one line). Use --pretty for indented, human-readable output, and -o/--output PATH to write to a file instead of stdout:

spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC --pretty
spotifyscraper album <id> -o album.json

Piping to jq

Compact JSON pipes straight into jq:

# Just the track name
spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC | jq -r '.name'

# Every artist on an album
spotifyscraper album <id> | jq -r '.artists[].name'

# Title + duration for each playlist track
spotifyscraper playlist <id> | jq -r '.tracks[].track | "\(.name) (\(.duration_ms)ms)"'

Pagination

playlist accepts --max-tracks and show accepts --max-episodes. Pass an integer to cap the count, or all (or 0) to fetch everything:

spotifyscraper playlist <id> --max-tracks 50      # at most 50 tracks
spotifyscraper playlist <id> --max-tracks all     # every track
spotifyscraper show <id> --max-episodes 10        # at most 10 episodes
spotifyscraper show <id> --max-episodes all       # every episode

--max-tracks defaults to 100 and --max-episodes defaults to 50.

Tuning the client

Every command takes the same client knobs:

Option	Effect
--proxy URL	Route requests through a proxy.
--timeout SECONDS	Per-request timeout (default 10).
--rate-limit N	Sustained requests per second (maps to RateLimit(per_second=N)).

spotifyscraper playlist <id> --rate-limit 1 --timeout 20 --proxy http://127.0.0.1:8080

See Anti-ban & resilience for guidance on choosing a rate.

Downloads

The download group writes media to a directory and prints the written path.

Cover art

spotifyscraper download cover <track-id> -o covers/
spotifyscraper download cover <track-id> --size smallest --name cover

Option	Effect
-o/--output DIR	Destination directory (default ., created if missing).
--size largest\|smallest	Pick the largest (default) or smallest available image.
--name NAME	Explicit filename; defaults to a sanitized entity name.

Preview clips

spotifyscraper download preview <track-id> -o previews/
spotifyscraper download preview <track-id> --embed-cover   # needs the media extra

Option	Effect
-o/--output DIR	Destination directory (default ., created if missing).
--embed-cover	Embed cover art and ID3 tags (requires spotifyscraper[media]).
--name NAME	Explicit filename; defaults to a sanitized entity name.

Previews are the ~30-second clips Spotify publishes publicly. Full-song downloads are not supported — see Media downloads.

Exit codes

Library errors are reported as a concise error: <message> on stderr (never a raw traceback) with a non-zero exit code:

Exit code	Meaning
0	Success.
1	A general SpotifyScraperError.
3	NotFoundError — the entity does not exist.
4	AuthenticationError — missing or expired credentials.

spotifyscraper track does-not-exist
# stderr: error: ...
echo $?   # 3

This makes the CLI safe to use in scripts with set -e.

Lyrics & transcripts

The lyrics and transcript commands are cookie-authenticated. lyrics fetches a track's time-synced lyrics; transcript fetches a podcast episode's transcript:

spotifyscraper lyrics 4uLU6hMCjMI75M1A2tKUQC --cookies cookies.txt
spotifyscraper transcript 07gKzPFkbvGF0cHoeG7ARS --cookies cookies.txt --pretty
# or: export SPOTIFY_SP_DC=... && spotifyscraper transcript <episode-id>

Both accept the same cookie sources and --pretty/-o options as the entity commands. An episode with no transcript exits 3 (NotFoundError). See the lyrics & cookies guide for how to obtain your sp_dc cookie.

Discovery & visual commands

More commands surface the discovery and visual data; all take the same --pretty/-o and client-tuning options.

Anonymous (no cookie):

Command	Fetches
spotifyscraper charts	Lists the built-in editorial charts
spotifyscraper charts <key>	A chart as a playlist (e.g. top-50-global)
spotifyscraper colors <image>	A cover image's theming colors
spotifyscraper related <artist>	"Fans also like" artists
spotifyscraper discography <artist>	Every release (--max-releases N\|all)
spotifyscraper similar <track>	Recommended albums (--limit N)
spotifyscraper events <artist>	Upcoming concerts

Cookie-authenticated (pass --cookies or set SPOTIFY_SP_DC):

Command	Fetches
spotifyscraper canvas <track>	A track's Canvas video (empty {} if none)
spotifyscraper credits <track>	Performers / writers / producers
spotifyscraper user <user-id>	A public user profile

spotifyscraper charts
spotifyscraper charts todays-top-hits --max-tracks 10 | jq -r '.tracks[].track.name'
spotifyscraper colors "https://i.scdn.co/image/ab67616d0000b273..."
spotifyscraper discography 0gxyHStUsqpMadRV0Di1Qt --max-releases all
spotifyscraper canvas 4LfCY65LvojKjWEnU7fNN4 --cookies cookies.txt

MCP server

A separate spotifyscraper-mcp command serves the library to LLM hosts over the Model Context Protocol. See the MCP server guide.