CLI Commands

Koel comes with a set of handy CLI commands to help you manage your installation. These commands are available via Laravel’s artisan command line interface.

You can run php artisan list from your Koel installation directory and pipe the output to grep to filter out those under the koel namespace:

php artisan list | grep koel
 koel
  koel:admin:change-password  Change a user's password
  koel:doctor                 Check Koel setup
  koel:init                   Install or upgrade Koel
  koel:license:activate       Activate a Koel Plus license
  koel:license:deactivate     Deactivate the currently active Koel Plus license
  koel:license:status         Check the current Koel Plus license status
  koel:podcasts:sync          Synchronize podcasts.
  koel:prune                  Remove empty artists and albums
  ...

In order to get help on a specific command, run php artisan <command> -h.

Available Commands

Warning

Always run commands as your web server user (e.g. www-data or nginx), never as root. Otherwise, Koel might encounter issues with file permissions (e.g. with cache and storage files) and you might end up with a broken installation.

With the Docker installation, for example, run the command as the www-data user:

docker exec --user www-data <container_name_for_koel> php artisan <command>

koel:admin:change-password

Change a user's password.

Usage

php artisan koel:admin:change-password [<email>]

Arguments

Name	Description
email	The user's email. If empty, will get the default admin user.

koel:admin:set-user-role

Set a user's role.

Usage

php artisan koel:admin:set-user-role <email>

Arguments

Name	Description
email	The user's email.

koel:clean-up-temp-files

Remove temporary files older than a certain age. Examples of temporary files include temporarily downloaded files, transcoded files, and so on.

Usage

php artisan koel:clean-up-temp-files

Options

Name	Description
--age=	The age of temporary files to remove in minutes. Defaults to 1440 (one day).

koel:doctor

Check Koel setup.

Usage

php artisan koel:doctor

koel:extract-folders

Extract the folder structure from the existing song paths and store it in the database. This command needs to be run only once. Subsequent scans will take care of this functionality automatically.

Usage

php artisan koel:extract-folders

koel:fetch-artwork

Attempt to fetch missing album covers and artist images from the available sources (Spotify, Last.fm, and MusicBrainz). You'll need to configure and enable the corresponding 3rd-party integrations for this command to work.

Note that Koel will only make a maximum of one request per second to avoid hitting the rate limits (if any) and risking getting blocked by the services.

Usage

php artisan koel:fetch-artwork

koel:init

Install or upgrade Koel.

Usage

php artisan koel:init [options]

Options

Name	Description
--no-assets	Do not compile front-end assets
--no-scheduler	Do not install scheduler

TIP

Instead of running php artisan koel:init directly, you should run composer koel:init, which calls this command under the hood after installing dependencies. To pass options to php artisan koel:init, use argument forwarding, e.g., composer koel:init -- --no-assets.

koel:license:activate

Activate a Koel Plus license.

Usage

php artisan koel:license:activate <key>

Arguments

Name	Description
key	The license key to activate.

koel:license:deactivate

Deactivate the currently active Koel Plus license.

Usage

php artisan koel:license:deactivate

koel:license:status

Check the current Koel Plus license status.

Usage

php artisan koel:license:status

koel:podcasts:sync

Synchronize podcasts.

Usage

php artisan koel:podcasts:sync

koel:prune

Remove empty artists and albums.

Usage

php artisan koel:prune

koel:scan

Scan for songs in the configured directory.

Usage

php artisan koel:scan [options]
php artisan koel:sync [options] # Alias, deprecated

Options:

Name	Description
O, --owner=	The ID of the user who should own the newly scanned songs. Defaults to the first admin user.
P, --private	Whether to make the newly scanned songs private to the user.
I, --ignore=	The comma-separated tags to ignore (exclude) from scanning. Valid tags are title, album,artist, albumartist, track, disc, year, genre, lyrics, and cover.
F, --force	Force re-scanning even unchanged files.

koel:scheduler:install

Install the command scheduler. Refer to Command Scheduling for more information.

koel:search:import

Import all searchable entities with Scout. Refer to Instant Search for more information.

Usage

php artisan koel:search:import

koel:storage

Set up and configure Koel’s storage.

Usage

php artisan koel:storage

koel:storage:dropbox

Set up Dropbox as the storage driver for Koel.

Usage

php artisan koel:storage:dropbox

koel:storage:local

Set up the local storage for Koel. A "local storage" is simply a directory on the server where Koel is installed.

Usage

php artisan koel:storage:local

koel:storage:s3

Set up Amazon S3 or a compatible service (DigitalOcean Spaces, Cloudflare R2, etc.) as the storage driver for Koel.

Usage

php artisan koel:storage:s3

TIP

To set up the storage driver for Koel, simply use koel:storage. Internally, it calls koel:storage:local, koel:storage:s3, or koel:storage:dropbox based on your input.

koel:tags:collect

Collect additional tags from existing songs. This is a legacy command and is no longer needed for new installations.

Usage

php artisan koel:tags:collect

Command Scheduling

Some commands, such as koel:scan, koel:prune, and koel:clean-up-temp-files can be scheduled to run at regular intervals. Instead of setting up individual cron jobs, you can use Koel’s built-in scheduler to automatically handle the commands for you.

To set up the scheduler, run the koel:scheduler:install command as the web server user (e.g. www-data or nginx):

php artisan koel:scheduler:install

Alternatively, you can manually add the following cron entry into the crontab of the webserver user (for example, if it's www-data, run sudo crontab -u www-data -e):

* * * * * cd /path-to-koel-installation && php artisan schedule:run >> /dev/null 2>&1

Either way, the scheduler will run every minute once installed, executing any scheduled commands as needed. By default, koel:scan, koel:prune, and koel:podcasts:sync are set to run every day at midnight.

Though you can still manually set up cron jobs for individual commands, the scheduler is the recommended approach to do command scheduling in Koel, as it will automatically cover any commands that may be added in the future.