Roon Command Line Control version 2

I have published a new release, version 2.0.0, of the RoonCommandLine package at


The RoonCommandLine package acts as a wrapper for the Roon Python API, adding a suite of command line tools to your Linux or Mac system that allow you to control Roon from the command line.

All RoonCommandLine commands utilize the Roon API to communicate with the Roon Core. RoonCommandLine tools can be executed locally on the same system where they are installed (run “roon -L” to enable local execution without SSH), or the commands can be executed remotely via SSH by copying the roon command to another system on the local area network and enabling SSH public key authentication between those systems.

Note: No modifications are made to the Roon Core by this package. Nothing is installed on the Roon Core by this package. The RoonCommandLine suite of tools and Roon Python API client all reside on a Linux or Mac system on the same local network as the Roon Core.


Currently the command line Roon control scripts provide support for:

  • Play album by album name
  • Play artist name
  • Play genre
  • Play playlist by playlist name
  • Play tag
  • Play Roon Radio
  • Issue one of the following commands in the specified zone
    • group
    • ungroup
    • play
    • pause
    • playpause
    • stop
    • next
    • previous
    • shuffle
    • unshuffle
    • repeat
    • unrepeat
    • mute
    • unmute
  • List albums, artists, genres, playlists, tags, or Roon zones
  • Select Roon audio zone or zone grouping

In addition, search capabilities have been added to the scripts
with partial matching facilities. Thus a substring can be supplied to use as a
search term with partial matching returning albums, artists, playlists, genres,
or tags which contain the specified substring.

All commands and playback can target a specified Roon output zone.


This release adds support for Debian and RPM format package installation, automated installation on Mac OS X, and greatly improved automated installation and configuration. Install the Debian or RPM package on a Linux system on the same local network as a Roon Core then execute the command roon -L to enable local execution of the Roon Python API. You should be able to execute Roon commands on that system (e.g. roon -l zones to get a list of Roon Zones, roon -a "Jethro Tull" to play artist Jethro Tull).


Download the latest Debian or RPM package format release

Debian based systems installation

Install the package on Debian based systems by executing the command

sudo apt install ./RoonCommandLine_2.0.0-1.deb

RPM based systems innstallation

Install the package on RPM based systems by executing the command

sudo yum localinstall ./RoonCommandLine-2.0.0-1.noarch.rpm

Debian based systems removal

Removal of the package on Debian based systems can be accomplished by issuing the command:

sudo apt remove rooncommandline

RPM based systems removal

Removal of the package on RPM based systems can be accomplished by issuing the command:

sudo yum remove RoonCommandLine

Mac OS X installation

To install on Mac OS X, clone the repository and execute the Install command:

git clone
cd RoonCommandLine

Mac OS X removal

git clone
cd RoonCommandLine

Great to see this.

And as the maintainer of the pyroon library I’d welcome changes if you need extra functions, or anything to make the setup easier to use.


@GregD , I apply a patch to the Python Roon API to add partial matching capability for searches. That should probably be merged into the pyroon repository. I will work up a pull request and submit it along with any other patches I think are suitable.


Great - PR very welcome!

1 Like

Why would I want a Command Line Control?

@Ton_R , good question. Most Roon users probably will never need or use command line control of Roon. I would say the most significant use case for command line control of anything is automation. For example, if I want to schedule playback of specified music in specific zones triggered by some event, then command line control can be used to implement this. That can be done via Cron jobs, play something in some zone at scheduled times. Or playback of specified songs in selected zones could be triggered by some event like when a particular face is recognized by my smart mirror or when my smart lights are turned to a particular profile. I use command line control of Roon coupled with Apple Siri voice commands that trigger an SSH shortcut to run the command. There are many use cases for automation using command line utilities.

The other main use case for command line control is simple convenience. If you spend a lot of time in a Shell environment then it is just easier to type a command that plays what you would like to hear where you want to hear it than it is to switch windows, bring up a GUI, click a few times to find what you want, and click to play it, then go back to your terminal window and Shell env. Most people do not live in a Shell environment like I do :slight_smile: so this use case is not that significant.

Finally, the command line interface and the associated Roon API can provide capabilities not available in the Roon GUI. Searching, listing, and filtering can be augmented by the plethora of tools available in a typical Shell environment. You can pipe the output of a Roon command to grep, sed, awk, yada yada and produce results unavailable in the GUI. That is, command line control along with the API and Shell utilities/builtins can extend the capabilities of the Roon audio system.

But, like I say, this is not going to be useful to most. It will hopefully be useful as a convenience for some and as one way to automate Roon playback and control.


Great, thanks for the response!

1 Like

As a fellow live-in-a-shell person, when I saw @Ton_R’s question I thought “Why wouldn’t you want to control Roon from the command line?” Thanks for putting this together!


I posted a release update, Version 2.0.1 Release1, which includes interactive menus, compatibility with new Python Roon API version 0.0.39, Manual Pages, completely automated installation and configuration, default local execution of commands averting the need for SSH public key authentication, Manual pages for all commands, and many bug fixes and improvements.

In this release, invoking the roon command with no arguments presents an interactive selection menu. All commands now have Manual Pages . Execute the command man <command-name> to view the Manual Page for a command. For example, man roon will present the roon Manual Page.

See Releases · Ron Record / RoonCommandLine · GitLab to download the latest release.


@Ronald_Record this is great! exactly what I’ve been looking for

Just a quick question about getting it set up with apple shortcuts - I can run commands directly in terminal from my iMac but when I try and pass the command in via SSH it comes up with an error 31 -

zsh:1: command not found: Roon

Any ideas what I’m missing? Does the port I use for the SSH shortcut matter? it’s currently set to 22

actually, I think I’ve worked that one out - I needed to pass the full path to the command so “/usr/local/bin/roon” instead of just “roon”

However the commands don’t seem to be doing anything now - they run and complete but don’t seem to be working. Any ideas?

I think there are complexities about environments on ssh shells - but I have no doubt someone who properly understands this will be along soon.

But assuming you’re running the command on your local mac you should be able to use the local shell (eh bash) rather than ssh, which may be easier to get running.

Thanks @GregD - I’ve been able to run commands using the local shell and they work fine. I was trying to take the next step and use SSH so I can use Siri voice commands and homekit buttons to control Roon

I think this is similar to the issue here.

But I’m definitely not a unix expert. Someone here will be!

Now all we need are a set of Emacs key bindings!

@Etk What is the ssh command you are trying to run? I can successfully run commands via ssh like the following:

ssh ronnie@ “/usr/local/bin/roon -r default”

Which plays the default live radio station configured in /usr/local/Roon/etc/roon_api.ini on the system with IP address

There are several areas of potential failure. Plus, it looks like you may be using zsh as your user’s shell. I have not tested with zsh so that may be a problem. But, it should work with zsh. Most often the issue with SSH use is the public key setup. The user on the executing end (in the example above the user is “ronnie”) needs to have the public key in their ~/.ssh/authorized_keys file. And the SSH service needs to be enabled on the system.

So, if you can run a roon command successfully at the command line on a system but you cannot run the same command via ssh from another system then it may be that ssh is not setup with the correct public key or the ssh service may not be enabled. Try something simple to verify ssh is enabled and the public key is setup.

ssh ronnie@ “echo foo”

Replace “ronnie” with your Roon user and the IP address with the IP address of the system on which you have RoonCommandLine installed. By “Roon user” I mean the user that is configured near the top of /usr/local/bin/roon in the line "user=“username”

If SSH is working with a simple echo command then it’s probably the RoonCommandLine setup or maybe your environment. But let’s start there. Can you run a simple command via ssh successfully? If so, we may need to look at your configuration files and environment.

@Ronald_Record thanks for the input - really helpful

So I am using the ssh implementation in apple shortcuts to try and call these roon commands. It’s set up to use SSH key and I can get a simple echo command running fine so I’m happy that it’s connecting ok.

When I put the roon command back in it looks like it runs ok in Shortcuts (no errors) but nothing seems to happen to Roon. The same command typed directly into terminal on the Mac running roon command line works fine.

I’m not seeing the line “user=username” - where should I look for that?

@Etk I’m trying to replicate what you have done but so far I am unable to reproduce this behavior. Can you provide me with additional details, as much as you wish to share? In particular, what are the commands you are trying to run via ssh in an apple shortcut? What did you use in all of the fields when filling out the shortcut (host, port, user, auth type, any input or variables, and exact command).

The “user=username” setting is in the roon shell script /usr/local/bin/roon. It is around line 23 of that script right after the server="xx.x.x.xx" setting. I want you to make sure the user you specified in the apple SSH shortcut is the same as the user setting in the roon shell script.

I hope you are having fun troubleshooting this with me :slight_smile: For me it’s educational and I am writing a wiki article on just this so it is helpful to have this feedback to highlight what I need to say in the article to make it easier to setup. But, if you get frustrated I can sympathize. SSH config is not easy, especially on a Mac as they swim in their own pond.

If I understand your situation correctly, you can successfully run an Apple SSH Shortcut using SSH Key authentication and a simple command - no error. The same type of shortcut using /usr/local/bin/roon ... apparently succeeds but does nothing while the exact same command in a terminal window succeeds and Roon plays whatever like expected. If that is correct, it is puzzling and I do not yet have a good guess as to the problem.

How do you have System Preferences -> Sharing -> Remote Login configured on the Mac?

@Etk maybe you do not wish to share some of the details of your setup and ssh shortcut config here on a public forum. Please feel free to email me at with details you feel comfortable sharing with me.

@Ronald_Record - I’m more than happy to troubleshoot this with you - thanks for taking the time! SSH is all a bit new to me but happy to learn as I go, everything was new once :smiley:

I’ve checked out the script and it didn’t have anything for the IP address so I’ve added that and the SSH name was just my first name rather than first name surname so I’ve fixed that too…

here are the settings for the Shortcuts script and the sharing remote login:

As you can see, if I edit the Shortcut and just do a simple shell command it works fine: