# Spotify on boxd

> Spotify is a digital music and podcast streaming service with millions of tracks, personalized playlists, and social sharing features.

- Page: https://boxd.sh/integrations/spotify/
- CLI: `run spotify` (88 commands, 8 marked common)
- SDK: `import { spotify } from "@boxd/run"`; every parameter and response type is at `@boxd/run/spotify`
- Triggers: 3
- Connect: `run auth spotify` (Sign in with Spotify), or https://app.boxd.sh/integrations/detail/spotify
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth spotify      # once: prints a link to connect your account
run spotify           # list its commands
run spotify get-show --help
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { spotify } from "@boxd/run";

const result = await spotify.getShow({ id: "…" });
console.log(result);

spotify.on("new-device", async (event) => {
  // New Device Added: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run spotify.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run spotify <command> --help` lists the optional ones. "common" marks what `run spotify` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-item-to-playback-queue` | `spotify.addItemToPlaybackQueue()` | `--uri` | 1 | Add an item to the end of the user's current playback queue |
| `add-items-to-playlist` ·common | `spotify.addItemsToPlaylist()` | `--playlist-id` `--uris` | 1 | Add one or more items to a user's playlist |
| `change-playlist-details` | `spotify.changePlaylistDetails()` | `--playlist-id` | 4 | Change a playlist's name and public/private state |
| `check-if-user-follows-artists-or-users` | `spotify.checkIfUserFollowsArtistsOrUsers()` | `--ids` `--type` | 0 | Check to see if the current user is following one or more artists or other Spotify users |
| `check-if-users-follow-playlist` | `spotify.checkIfUsersFollowPlaylist()` | `--ids` `--playlist-id` | 0 | Check if the current authenticated user is following a specified playlist |
| `check-user-s-saved-albums` | `spotify.checkUserSSavedAlbums()` | `--ids` | 0 | Check if one or more albums is already saved in the current Spotify user's 'Your Music' library |
| `check-user-s-saved-audiobooks` | `spotify.checkUserSSavedAudiobooks()` | `--ids` | 0 | Check if one or more audiobooks are already saved in the current Spotify user's library |
| `check-user-s-saved-episodes` | `spotify.checkUserSSavedEpisodes()` | `--ids` | 0 | Check if one or more podcast episodes are saved in the current Spotify user's 'Your Episodes' library |
| `check-user-s-saved-shows` | `spotify.checkUserSSavedShows()` | `--ids` | 0 | Check if one or more shows is already saved in the current Spotify user's library |
| `check-user-s-saved-tracks` | `spotify.checkUserSSavedTracks()` | `--ids` | 0 | Check if one or more tracks is already saved in the current Spotify user's 'Your Music' library |
| `create-playlist` ·common | `spotify.createPlaylist()` | `--name` `--user-id` | 3 | Create a playlist for a Spotify user |
| `follow-artists-or-users` | `spotify.followArtistsOrUsers()` | `--ids` `--type` | 0 | Follow one or more artists or Spotify users on behalf of the current authenticated user |
| `follow-playlist` | `spotify.followPlaylist()` | `--playlist-id` | 1 | Add the current user as a follower of a playlist |
| `get-album` | `spotify.getAlbum()` | `--id` | 1 | Get Spotify catalog information for a single album |
| `get-album-tracks` | `spotify.getAlbumTracks()` | `--id` | 3 | Get Spotify catalog information about an album's tracks |
| `get-artist` | `spotify.getArtist()` | `--id` | 0 | Get detailed Spotify catalog information for a single artist |
| `get-artist-s-albums` | `spotify.getArtistSAlbums()` | `--id` | 4 | Get Spotify catalog information about an artist's albums |
| `get-artist-s-related-artists` | `spotify.getArtistSRelatedArtists()` | `--id` | 0 | Get Spotify catalog information about artists similar to a given artist |
| `get-artist-s-top-tracks` ·common | `spotify.getArtistSTopTracks()` | `--id` | 1 | Get Spotify catalog information about an artist's top tracks by country/market |
| `get-audiobook` | `spotify.getAudiobook()` | `--id` | 1 | Get Spotify catalog information for a single audiobook |
| `get-audiobook-chapters` | `spotify.getAudiobookChapters()` | `--id` | 3 | Get Spotify catalog information about an audiobook's chapters |
| `get-available-devices` | `spotify.getAvailableDevices()` | — | 0 | Get information about the user's available Spotify Connect devices |
| `get-available-genre-seeds` | `spotify.getAvailableGenreSeeds()` | — | 0 | Get available genre seeds for Spotify recommendations |
| `get-available-markets` | `spotify.getAvailableMarkets()` | — | 0 | Get the list of markets where Spotify is available |
| `get-category-s-playlists` | `spotify.getCategorySPlaylists()` | `--category-id` | 2 | Get Spotify playlists tagged with a specific category (e.g., 'workout', 'party', 'dinner') |
| `get-chapter` | `spotify.getChapter()` | `--id` | 1 | Get Spotify catalog information for a single audiobook chapter including name, description, duration, release date, narrators, and playback information |
| `get-current-user-s-playlists` | `spotify.getCurrentUserSPlaylists()` | — | 2 | Get a list of the playlists owned or followed by the current Spotify user |
| `get-current-user-s-profile` | `spotify.getCurrentUserSProfile()` | — | 0 | Get detailed profile information about the current authenticated user |
| `get-currently-playing-track` | `spotify.getCurrentlyPlayingTrack()` | — | 2 | Get the object currently being played on the user's Spotify account |
| `get-episode` | `spotify.getEpisode()` | `--id` | 1 | Get Spotify catalog information for a single podcast episode identified by its unique Spotify ID |
| `get-featured-playlists` | `spotify.getFeaturedPlaylists()` | — | 3 | Get a list of Spotify's editorially curated featured playlists |
| `get-followed-artists` | `spotify.getFollowedArtists()` | `--type` | 2 | Get all artists followed by the current user |
| `get-new-releases` | `spotify.getNewReleases()` | — | 2 | Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player's "Browse" tab) |
| `get-playback-state` | `spotify.getPlaybackState()` | — | 2 | Get information about the user's current playback state, including track or episode, progress, and active device |
| `get-playlist` ·common | `spotify.getPlaylist()` | `--playlist-id` | 3 | Get a playlist owned by a Spotify user |
| `get-playlist-cover-image` | `spotify.getPlaylistCoverImage()` | `--playlist-id` | 0 | Get the current image(s) associated with a specific playlist |
| `get-playlist-items` | `spotify.getPlaylistItems()` | `--playlist-id` | 5 | Get full details of the items of a playlist owned by a Spotify user |
| `get-recently-played-tracks` | `spotify.getRecentlyPlayedTracks()` | — | 3 | Get tracks from the current user's recently played tracks. _Note: Currently doesn't support podcast episodes._ |
| `get-recommendations` | `spotify.getRecommendations()` | — | 47 | Get track recommendations based on seed artists, genres, and/or tracks |
| `get-several-albums` | `spotify.getSeveralAlbums()` | `--ids` | 1 | Get Spotify catalog information for multiple albums identified by their Spotify IDs |
| `get-several-artists` | `spotify.getSeveralArtists()` | `--ids` | 0 | Get Spotify catalog information for several artists based on their Spotify IDs |
| `get-several-audiobooks` | `spotify.getSeveralAudiobooks()` | `--ids` | 1 | Retrieve Spotify catalog information for multiple audiobooks in a single request |
| `get-several-browse-categories` | `spotify.getSeveralBrowseCategories()` | — | 3 | Get a list of categories used to tag items in Spotify (on, for example, the Spotify player's "Browse" tab) |
| `get-several-chapters` | `spotify.getSeveralChapters()` | `--ids` | 1 | Get Spotify catalog information for several audiobook chapters identified by their Spotify IDs |
| `get-several-episodes` | `spotify.getSeveralEpisodes()` | `--ids` | 1 | Get Spotify catalog information for several episodes based on their Spotify IDs |
| `get-several-shows` | `spotify.getSeveralShows()` | `--ids` | 1 | Get Spotify catalog information for several shows (podcasts) based on their Spotify IDs |
| `get-several-tracks` | `spotify.getSeveralTracks()` | `--ids` | 1 | Get Spotify catalog information for multiple tracks based on their Spotify IDs |
| `get-several-tracks-audio-features` | `spotify.getSeveralTracksAudioFeatures()` | `--ids` | 0 | Get audio features for multiple tracks based on their Spotify IDs |
| `get-show` ·common | `spotify.getShow()` | `--id` | 1 | Get Spotify catalog information for a single show (podcast) identified by its unique Spotify ID |
| `get-show-episodes` ·common | `spotify.getShowEpisodes()` | `--id` | 3 | Get Spotify catalog information about a show's episodes |
| `get-single-browse-category` | `spotify.getSingleBrowseCategory()` | `--category-id` | 1 | Get a single category used to tag items in Spotify (on, for example, the Spotify player's "Browse" tab) |
| `get-track` | `spotify.getTrack()` | `--id` | 1 | Get Spotify catalog information for a single track identified by its unique Spotify ID |
| `get-track-s-audio-analysis` | `spotify.getTrackSAudioAnalysis()` | `--id` | 0 | Get a comprehensive audio analysis for a Spotify track |
| `get-track-s-audio-features` | `spotify.getTrackSAudioFeatures()` | `--id` | 0 | Get audio feature information for a single track identified by its unique Spotify ID |
| `get-user-s-playlists` | `spotify.getUserSPlaylists()` | `--user-id` | 2 | Get a paginated list of playlists owned or followed by a Spotify user |
| `get-user-s-profile` | `spotify.getUserSProfile()` | `--user-id` | 0 | Get public profile information about a Spotify user |
| `get-user-s-queue` | `spotify.getUserSQueue()` | — | 0 | Get the list of tracks and episodes in the user's playback queue |
| `get-user-s-saved-albums` | `spotify.getUserSSavedAlbums()` | — | 3 | Get a list of albums saved in the current Spotify user's library ('Your Music') |
| `get-user-s-saved-audiobooks` | `spotify.getUserSSavedAudiobooks()` | — | 2 | Get a list of the audiobooks saved in the current Spotify user's 'Your Music' library |
| `get-user-s-saved-episodes` | `spotify.getUserSSavedEpisodes()` | — | 3 | Get a list of episodes saved in the current Spotify user's library |
| `get-user-s-saved-shows` | `spotify.getUserSSavedShows()` | — | 2 | Get a list of shows saved in the current Spotify user's library |
| `get-user-s-saved-tracks` | `spotify.getUserSSavedTracks()` | — | 3 | Get a list of the songs saved in the current Spotify user's 'Your Music' library |
| `get-user-s-top-artists` | `spotify.getUserSTopArtists()` | — | 3 | Get the current user's top artists based on calculated affinity |
| `get-user-s-top-tracks` | `spotify.getUserSTopTracks()` | — | 3 | Get the current user's top tracks based on calculated affinity |
| `pause-playback` | `spotify.pausePlayback()` | — | 1 | Pause playback on the user's account |
| `remove-playlist-items` | `spotify.removePlaylistItems()` | `--playlist-id` `--tracks` | 1 | Remove one or more items from a user's playlist |
| `remove-user-s-saved-audiobooks` | `spotify.removeUserSSavedAudiobooks()` | `--ids` | 0 | Remove one or more audiobooks from the current user's Spotify library |
| `remove-user-s-saved-episodes` | `spotify.removeUserSSavedEpisodes()` | `--ids` | 0 | Remove one or more episodes from the current user's library |
| `remove-user-s-saved-shows` | `spotify.removeUserSSavedShows()` | — | 2 | Delete one or more shows from current Spotify user's library |
| `remove-user-s-saved-tracks` | `spotify.removeUserSSavedTracks()` | — | 2 | Remove one or more tracks from the current user's 'Your Music' library |
| `remove-users-saved-albums` | `spotify.removeUsersSavedAlbums()` | `--ids` | 0 | Remove one or more albums from the current user's 'Your Music' library |
| `save-albums-for-current-user` ·common | `spotify.saveAlbumsForCurrentUser()` | `--ids` | 0 | Save one or more albums to the current user's 'Your Music' library |
| `save-audiobooks-for-current-user` | `spotify.saveAudiobooksForCurrentUser()` | `--ids` | 0 | Save one or more audiobooks to the current user's library |
| `save-episodes-for-current-user` | `spotify.saveEpisodesForCurrentUser()` | `--ids` | 0 | Save one or more podcast episodes to the current user's library |
| `save-shows-for-current-user` | `spotify.saveShowsForCurrentUser()` | `--ids` | 0 | Save one or more shows to current Spotify user's library |
| `save-tracks-for-current-user` ·common | `spotify.saveTracksForCurrentUser()` | — | 2 | Save one or more tracks to the current user's 'Your Music' library |
| `search-for-item` | `spotify.searchForItem()` | `--q` `--type` | 4 | Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string |
| `seek-to-position` | `spotify.seekToPosition()` | `--position-ms` | 1 | Seek to a specific position in the user's currently playing track |
| `set-playback-volume` | `spotify.setPlaybackVolume()` | `--volume-percent` | 1 | Set the volume for the user's current playback device |
| `set-repeat-mode` | `spotify.setRepeatMode()` | `--state` | 1 | Set the repeat mode for the user's playback |
| `skip-to-next` | `spotify.skipToNext()` | — | 1 | Skips to next track in the user's queue |
| `skip-to-previous` | `spotify.skipToPrevious()` | — | 1 | Skips to the previous track in the user's queue |
| `start-resume-playback` | `spotify.startResumePlayback()` | — | 5 | Start a new context or resume current playback on the user's active device |
| `toggle-playback-shuffle` | `spotify.togglePlaybackShuffle()` | `--state` | 1 | Toggle shuffle on or off for user's playback |
| `transfer-playback` | `spotify.transferPlayback()` | `--device-ids` | 1 | Transfer playback to a new device and optionally begin playback |
| `unfollow-artists-or-users` | `spotify.unfollowArtistsOrUsers()` | `--ids` `--type` | 0 | Remove the current user as a follower of one or more artists or other Spotify users |
| `unfollow-playlist` | `spotify.unfollowPlaylist()` | `--playlist-id` | 0 | Remove the current user as a follower of a playlist |
| `update-playlist-items` | `spotify.updatePlaylistItems()` | `--playlist-id` | 5 | Either replace all tracks in a playlist OR reorder existing tracks within it |

## Triggers

`spotify.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"new-device"` | New Device Added | — | Triggers when a new device is added |
| `"playlist-item"` | Spotify Playlist Item Change | `playlist_id` | Triggers when songs are added to or removed from a Spotify playlist |
| `"playlist"` | New Playlist Created or Deleted | — | Triggers when a new playlist is created or deleted |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.