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

Then:

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:

[default]
spt_client_id=a02b6c2ef3e7
spt_client_secret=4e11b25b6f
spt_refresh_token=AQChZXEeZs0r8wNdLaQmCxtORFIh5j4

[dev]
spt_client_id=a02b6c2ef3e7
spt_client_secret=4e11b25b6f
spt_refresh_token=AQChZXEeZs0r8wNdLaQmCxtORFIh5j4
note

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>

Examples:

# 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]
tip

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]