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 14.

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. 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:



The CLI automatically looks for this file, uses it to generate an access token and passes it to the subcommand.


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. A custom profile can be selected by passing the --profile flag to any subcommand. If no profile is specified, "default" is used. For example:

spotifly [subcommand] --profile dev [...args]

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]

Version and help

Invoke any command with no arguments to see the version and available commands. This is equivalent to passing the --help flag. Of course, the classic --version flag is supported as well.

# CLI installed

# From NPM
npx @spotifly/cli --version