Roon Command Line Control

I have published a set of Bash and Python scripts I use to control Roon via the command line on Unix/Linux/Mac or anywhere Bash/Python/SSH are supported. These scripts use SSH to execute commands on a system with the Python Roon API installed (roonapi · PyPI). The Python Roon API then sends commands to the Roon Core via the Roon API. This release of the Roon Command Line tools includes a patch to the Python Roon API which enables searches of the Roon library based on substrings. Using such searches it is possible to retrieve, for example, all playlists that contain the word “Best” or all albums with titles containing the words “Greatest Hits”.

Most of this functionality can be accomplished via the Roon Remote GUI. The command line tools provided here are not intended to provide new functionality but rather to provide a useful subset of functionality accessible via the command line. So, if you are not a command line sort of person and do not spend a lot of time in terminal windows then this project may be of no interest to you. However, I find it useful since I do spend a lot of time in terminal windows and issuing a command like “roon -a Donovan” to play songs by artist “Donovan” is a lot easier than switching windows to the Roon Remote and searching for Donovan then pressing play. YMMV.

Another area in which command line control of Roon is useful is automation. Any system of automation that can utilize SSH can be used to automate Roon with these command line tools. For example, Apple Shortcuts can be configured to use SSH and execute a command on a remote system. Thus Siri or any form of automatic control can be implemented to run a Shortcut which plays an artist, album, playlist, genre, or starts/pauses/etc Roon. I don’t know Android as well but if there is an automated way to run SSH commands then something similar could be done with Android phones. The Roon Command Line project can be used for automating control of Roon via voice, shortcut execution, cron jobs, etc.

The project is new and there are plenty of areas for improvement/extension. The current release includes support for playback of albums, artists, genres, playlists, Radio Paradise, and tags with zone selection for each. In addition, commands to play|pause|stop|next|previous|shuffle|unshuffle|repeat|unrepeat|mute|unmute can be issued by zone and searches can be performed by exact match or substring.

In order to run the Roon Command Line tools, you will need some familiarity with SSH setup/configuration as Public Key authentication is used to provide SSH access. Further, the command line tools require the installation of the Python Roon API which uses pip and Python3 so a system running Python3 and pip is required. If these requirements are satisfied the installation and configuration of the Roon Command Line tools is automated to some extent.

Releases can be downloaded at

See the README at for an Installation and Usage overview.


The links you give don’t work - on a hunch I changed gitlab to github, and found your project. :slight_smile:

Thanks Brian, the project on Gitlab was set to Private. My mirror of the project on Github is public. I changed the settings on the Repo so it is now Public on Gitlab. The links should now work ok. Let me know if you have any problem.

Thanks a bunch for this, really appreciate you taking the time to put this together.

1 Like

Thanks so much for this. When I read what you’d put together, I immediately got several ideas of things I could do with a command line controller for Roon.

Full disclosure: Although I’ve been working professionally in programming for longer than I’d like to admit, I’ve been on the Microsoft side of things, and that means I’m fairly new to Git/Bash/Python… but all is not lost. I’ve dabbled in all of the above, and you can still teach this old dog new tricks. :slight_smile:

I managed to get this cloned from GitLab and running in Windows Subsystem for Linux. The installation seemed to go as outlined in the README, but I’m not sure what I’ve done wrong because when I run list_zones, I get the output below and nothing else:

snoker@SN-THREADRIPPER:~/RoonCommandLine$ list_zones
2021-04-12 11:43:31,871 INFO roonapi – Connecting to Roon server
2021-04-12 11:43:31,879 INFO roonapi – Connection with roon websockets (re)created.
2021-04-12 11:43:31,879 INFO roonapi – Confirming previous registration with Roon…
2021-04-12 11:43:31,897 INFO roonapi – Registered to Roon server SN-MUSIC

If I run any other “list” command, I get a “list index out of range error” similar to this:
Traceback (most recent call last):
File “”, line 47, in
output_id = [
IndexError: list index out of range

Keeping in mind that it’s more than likely a newbie mistake on my end, do you have any suggestions?

Thanks for trying this out Shawn. I have not run the Roon Command Line tools in a Windows Subsystem for Linux so it will be interesting to see if this works. I will try to help. There are a couple of areas I suspect users will initially stumble over. One is the setup for public key authentication in SSH. Did you get this setup correctly? Can you ssh from your Windows Subsystem for Linux to the system running the Python Roon API package without the need for entering credentials?

The other area that may be causing problems is the installation of the Python Roon API package and its ability to communicate with your Roon Core. To debug problems I have found it useful to SSH in to the system running the Python Roon API package and run commands by hand there. For example, rather than running the list_zones command, SSH in as the configured user, cd to the appropriate directory, and run “python -z YOUR_ZONE_NAME”.

Another area I expect will be problematic is the configuration settings. Some defaults are provided but these will no doubt need to be modified. There are two primary configuration files, both on the system where the Python Roon API was installed. These are the files “$HOME/.pyroonconf” and “$HOME/RoonCommandLine/roon_api.ini”. Make sure these two configuration files have valid entries. For example, in roon_api.ini verify that the DefaultZone setting is valid for your setup. By default, the DefaultZone is set to “Living Room”. If you do not have a Roon Zone named “Living Room” then this is going to cause problems. I tried to dynamically configure as best I could but really all I have done thus far is set the IP addresses and a few other variables. Setting the default artist and album and zone and so on is still left to you. If you provide me with the contents of these two configuration files I can maybe help you set them up.

I am happy to assist but I also realize this is not as easy as it should be right now. Helping you will help me to make it easier in future releases.

1 Like

I am excited to try this in my system, looking to better integrate my control system with the audio playback. Do you know if this will work with an Elac Discovery. The Elac unit is running the Roon Essentials v1.7 (it has not been updated to 1.8 yet).

Hi, sorry, no I do not know if this will work with an Elac Discovery or with v1.7. But I would be interested to find out. Let me know how it goes. I will try to help if you run into problems.

Thank you for the pointers. With that information I was able to get almost all of this working. I’ll summarize here what I did in order to help you or anyone who is interested do the same.

For the record, my Roon Core is a Windows Server 2019 machine, but all of the work I’ve done is on a Windows 10 20H2 (19042.867) machine, running Windows Subsystem for Linux (Ubuntu 20.04.2 LTS).

You mentioned the default settings in roon_api.ini. I had found this file before I posted the first time and I did need to change the IP address and the Default Zone. The IP address that it had grabbed and inserted in there was for a VirtualBox adapter. I would imagine that most users won’t be running VMs on their machines, so you probably don’t need to account for that.

I was oblivious to the .pyroonconf file, so the ROON_ZONE value in there was incorrect, and I changed that after you mentioned it.

At this point, I was able to follow your directions and run the python commands. For example, “python -z MY_ZONE” returned my zone name. This was encouraging.

From there, I set out to get the public key authentication in SSH working. I had already generated a key pair when I cloned from Git, so I Googled and found the steps that I needed. I tried

ssh-copy-id @destination-IP

but I got a “connection refused” message.

I Googled some more and discovered that the ssh service wasn’t running on the destination machine. (How silly.) I ran

sudo service ssh start

to start it.

I tried the
ssh-copy-id @destination-IP

command again, and this time I got Permimssion denied (publickey)

This time more Googling led me to the following steps. I’m not sure why this worked, or even if it’s a good security practice, but since I reverted the config change at the end, it seems safe enough to me.

sudo nano /etc/ssh/sshd_config
Change this line: PasswordAuthentication no
To PasswordAuthentication yes
Save / Exit

ssh-copy-id @my.IP

This time it succeeded.

Then I reverted my changes to sshd_config so that the line read

PasswordAuthentication no

At this point I was able to SSH in to the system running the Python Roon API package and I could run the roon commands and most of them worked for me.

For example,

  • roon -l zones lists all my active zones
  • roon -g Pop/Rock plays the genre Pop/Rock
  • roon -p “Billy Joel” plays the Billy Joel playlist
  • roon -a Blondie plays tracks by Blondie
  • roon -A Autoamerican plays the album Autoamerican
  • roon -c All of the controls work

Most of the scripts are working! The only ones that are giving me trouble are the lists. For example, I have playlists called Pete Townsend, Peter Frampton, and Peter Gabriel. If I run this command:

roon -l playlists -s Pete

I would expect it to list those three. Instead, I get this error:

Traceback (most recent call last):
File “”, line 54, in
playlists = roonapi.list_media(output_id, [“Playlists”, searchterm])
AttributeError: ‘RoonApi’ object has no attribute ‘list_media’

I get the same error if I use a search string that’s an exact match for a playlist name. Similar attempts to use roon -l to lists artists or albums result in the same error on line 54.

I know this was an extremely long post that will likely interest very few, but if it helps a few folks, it was worth it.

For now, I’m off and running because my first goal is to use automation to kick off playlists, and that’s accomplished. I appreciate your help, Ronald, and I hope you find my feedback useful. I can continue to provide information if you need it.