Skip to main content

Command Line

Installing the CLI

Spotifly's wrapper CLI can be installed globally. It ships with the latest versions of all executables (as subcommands) from this project. The CLI and all other packages require at least Node 18.

yarn global add @spotifly/cli@latest
npm install -g @spotifly/cli@latest


spotifly [subcommand] [args...]

Configuration and Auto-Authentication

Many CLI operations require an access token to talk to the Spotify API - usually in the form of a --token command line argument. If you don't want to manually generate one every time you use the CLI, you can optionally create a .spotifly config file in your home directory. You'll need to add at least a profile named "default" if you want to use an access configuration file. For example:



A .spotifly config file in the current directory takes precedence over configuration in your home directory.

Using Profiles

The INI format allows you to create multiple profiles. Each profile must have the three keys depicted above. All subcommands that accept a --token flag also accept a --profile flag as an alternative. You need to provide either. Here's how profiles and tokens work together:

  1. If --token <token> is provided, the app will use the token and ignore all profiles
  2. If no token and no --profile flag is provided, the app will look for a profile with the name default
  3. If a --profile <profile> flag is provided, the app will look for a profile with the name <profile>


# Implicitly use the default profile
spotifly library

# Use the dev profile
spotifly library --profile dev

Currently, the following packages support profiles:

Listing Profiles

You can list all available profiles using:

spotifly profiles

Why would you use different profiles?

Remember: Spotify refresh tokens are created for a spotify application and bound to a user and access scope. Hence, you may have multiple profiles for a single spotify application, whereas the client id and secret are the same. The refresh tokens, however, may be different. You could have a profile for readonly access, another for read/write access, etc.

Why does this require a configuration file?

Why can't I just pass my long-term credentials as flags? It is a very bad idea to read secrets from flags. Long story short is that your credentials will leak to other places like your shell history. Hence, only reading from a configuration file is supported.

Usage with NPX / Yarn DLX

Instead of installing the CLI, every package can also be invoked directly with npx. This will download and save the executable in npm's local cache but not permanently add it to the PATH. How NPX works.

npx @spotifly/cli@latest [...args]

Alternatively, if you're in a workspace that uses Yarn Berry, you can use yarn dlx.

yarn dlx @spotifly/cli@latest [...args]

If a package is invoked with npx and not in the cache, a prompt will ask you to install it. You can suppress the prompt by adding --yes right after npx. This is useful if you want to run any command in a CI/CD environment.

npx --yes @spotifly/cli@latest [...args]