Sailfish OS ‑ Command Line Interface & Customisation

This article has a parent article. It contains some preliminaries to the topics here.

Doing Things on the Command Line

MTP (the same protocol Android devices use) will expose the /home/defaultuser folder to the connecting computer, both to graphical and command line applications. But it hides some (system) files and folders from the connected system.

A more powerful way is to connect through a terminal via SSH:


Please be prepared that you might need to use the terminal app on the phone if you lock yourself out.

Don't be root for any of these commands/edits, except where specified!

Another option is to enable Developer mode & Remote connection, then ssh into the device or scp files to/from it via WLAN.
Example config section in ~/.ssh/config on the computer that wants to connect to the phone:

Host xa2 # make something up here HostName # Port XXX # your choice here User defaultuser IdentityFile /home/me/.ssh/name-of-id

The IP can be different - tell your router to give your phone always the same IP.
Now entering

$> ssh xa2

should be enough to make a connection. It asks for the password you entered when enabling developer mode & remote connections.

When this is working, I (along with 99% of all Linux users) highly recommend using an SSH key for connecting, for improved security against attacks. The procedure is exactly the same as on any other GNU/Linux system, see e.g. [here for a tutorial][awsk].

One should also disable password and root login completely: as root (devel-su), edit /etc/ssh/sshd_config on the phone and add/edit/uncomment at least these lines:

PermitRootLogin no # Port XXX # your choice here PasswordAuthentication no PubkeyAuthentication yes ChallengeResponseAuthentication no AllowUsers defaultuser

Remember to restrict access to ~/.ssh/ and the files in it, otherwise ssh won't let you use the keys and you might lock yourself out!

chmod 700 ~/.ssh
chmod 600 ~/.ssh/*

Restart sshd on the phone:

devel-su systemctl restart sshd.service

You should now be able to connect with your key file, not using the local user's password anymore.

Also consider changing the default port 22 to something else by uncommenting the lines in both config files, and restarting sshd again.

The phone's shell and my beloved URxvt terminal emulator have difficulties communicating. I installed xterm on my computer and am using this to connect to the phone. Works perfectly.

Of course one can always use the terminal app directly on the phone. It gives full access to the system just like SSH.

Becoming root

devel-su asks for the user password and can be used for both single commands and to open a root shell.

PackageKit a "high-level front end for a number of different package management systems." It's installed by default on SailfishOS. It uses the ZYpp package manager as a backend, which in turn uses rpm. Simply entering pkcon will list commands and options.


On your phone, you might want to install nano, a useful & ubiquitous CLI editor:
devel-su pkcon install nano

It does not come with a nanorc file; I recommend copying one from another machine and moving it to /etc/nanorc. That way settings apply to all users. Make sure to enable syntax highlighting by adding this line:
include "/usr/share/nano/*.nanorc"


By default, /bin/bash is symlinked to busybox:

$> ls -l $(which $0)
lrwxrwxrwx  1 root root  18 Feb 13 2023  /bin/bash -> ../usr/bin/busybox

So even if you explicitely start bash, it starts busybox instead.

However, bash is already installed as /usr/bin/bash - we just need to remove one package:

$> devel-su pkcon remove busybox-symlinks-bash


To view & edit SQLITE databases directly on the phone. The sqlite3 executable is not installed, but the package sqlite is available. It does not show up in either Jolla or Openrepos appstores, but you can install it like this:

[root@Your_Phone]# pkcon install sqlite


SSHFS can mount part of a remote filesystem locally via ssh.

On SailfishOS this means that I can listen to music or watch video straight from that remote location - no more media servers! In fact I can access all files with both GUI and CLI applications.

Here's how:

First, try to get normal ssh working from your phone to a server, preferably passwordless with an authentication key. Once this works reliably:

  • Install sshfs-fuse-2 (OpenRepos/Storeman). Don't be alarmed by its age, it uses SailfishOS' very own ssh binary to make a secure connection!

  • formulate a suitable command or use a toggle script like this one:

    #!/bin/bash exec 2>&1 # dependency checks for dep in mount grep sshfs ssh fusermount; do command -V $dep >/dev/null || exit 1 done mountdir="/home/defaultuser/server" # just an example location="remote_user@domain_or_IP:/path/to/dir" port=XXX # preferably something other than 22! identity="/home/defaultuser/.ssh/your_server_s_key_file" sshfs_options="follow_symlinks,ServerAliveInterval=15,reconnect,\ IdentitiesOnly=yes,IdentityFile=$identity,port=$port,\ compression=yes,debug,sshfs_debug,loglevel=debug" if [[ $(mount|grep -o "$mountdir") == "$mountdir" ]] then echo "$mountdir is already mounted. Unmounting..." fusermount -u -z "$mountdir" exit 0 fi if sshfs -C -o "$sshfs_options" "$location" "$mountdir" & then echo "Mounted $location on $mountdir" echo "Run $0 again to terminate connection." exit 0 else echo "Mounting $location failed" fusermount -u -z "$mountdir" exit 1 fi

Executing the script the first time will mount, executing it another time will unmount. It's very chatty, if you need to use the terminal it was started in you might want to remove all three debug options.


Ambiences can be quickly created from images/photos, but I find this process a little lacking: images are resized in a way that can reduce their quality, and I do not have enough control over the colours used.
The default ambiences are stored in /usr/share/ambience. They are simple folders with a configuration file (*.ambience), a background image and optionally also sounds.
Everything is straigthforward. You can create your own ambiences from scratch, however they need to be stored in /usr/share/ambience, I have not found a way to store them anywhere under /home/defaultuser.

Here's an example:

$> ls /usr/share/ambience/white-on-black/*
$> cat /usr/share/ambience/white-on-black/white-on-black.ambience
    "displayName"               : "White on Black",
    "wallpaper"                 : "black.png",
    "highlightColor"            : "#ffffff",
    "secondaryHighlightColor"   : "#dddddd",
    "primaryColor"              : "#ffffff",
    "secondaryColor"            : "#aaaaaa",
    "ringerVolume"              : 100,
    "colorScheme"               : "lightondark",
    "favorite"                  : true,
    "timestamp"                 : "2021-09-19T10:00:00",
    "version"                   : 3

The image should be the height of your phone's screen, and square. In my case: 1920x1920px.

You will need to be root (devel-su) to create & edit these files & folders.
There's also an option to create a package directly on your phone, but I haven't gone to such lengths.

When ready, restart the ambience daemon: systemctl --user restart ambienced.

Also have a look at the other .ambience files:

Disable High Volume Warning

Disclaimer: be aware that doing this you remove a safety feature and could damage your hearing. Use at your own risk.

It's the same idiotic warning one also gets on Android phones when listening on headphones (or anything pugged into the audio jack). It blocks raising the volume above a certain level until some sort of OK button is tapped. Listening to audio while cycling, this gets very annoying, because it kicks in seemingly randomly once or twice a day.

To get rid of it, you can install Patchmanager 3.0 and select "Disable High Volume Warning" from the Web catalog, install it, then Apply.
Since the last OS-update (4.0.x) there does not seem to be a suitable patch anymore.
Patchmanager is now in CHUM (compatible with as of right now) and the "Disable High Volume Warning" is found in the Web catalog.

Other Methods

To completely disable it, edit /etc/pulse/mainvolume-listening-time-notifier.conf (also see "SSH" and "Becoming root" from the main article). Replace

mode-list = lineout,hs


#mode-list = lineout,hs
mode-list = 

Alternatively you can also comment out every line in the file, or move it to a place where pulseaudio does not see it anymore, e.g.:

mv /etc/pulse/mainvolume-listening-time-notifier.conf ..

And reboot.


It appears to be completely gone after that, I can always raise the volume as high as it goes, but I cannot shake the feeling that the maximum volume sometimes doesn't go as high as it used to. I still have a lot to learn about pulseaudio, especially on this device. In any case, after the latest upgrade this change was gone. I'm taking the chance to try something different.

Collection of Notes

I found this pastebin (archive) with a gdb of pulseaduio. It shows me which module loads the config file in question and what it does with it:

D: [pulseaudio] module-meego-mainvolume.c: Read long listening time notifier config from /etc/pulse/mainvolume-listening-time-notifier.conf
D: [pulseaudio] conf-parser.c: Parsing configuration file '/etc/pulse/mainvolume-listening-time-notifier.conf'
D: [pulseaudio] module-meego-mainvolume.c: Notifier conf role-list add: "x-maemo"
D: [pulseaudio] module-meego-mainvolume.c: Notifier conf mode-list add: "lineout"
D: [pulseaudio] module-meego-mainvolume.c: Notifier conf mode-list add: "hs"
D: [pulseaudio] listening-watchdog.c: Restore counter value 0 minutes (0 seconds)
D: [pulseaudio] module-meego-mainvolume.c: Long listening time notifier setup done.

Not that I understand very much, but I wonder what will happen if i simply remove/rename that file. A search for listening-watchdog finds a file in ~/.config/pulse with a .simple extension. It is not plain text, I have no idea what to do with it.
There is some documentation about pulseaudio modules.

It is possible to install gdb, as well as alsa-utils:

pkcon install gdb alsa-utils

Alsamixer is unusable but I can get some information through aplay, amixer etc.


Tools for interacting with mce (Mode Control Entity).

#> zypper install mce-tools

Provides the command line tool mcetool which allows to set and read various - well, modes on your phone.
Try mcetool -h.
E.g.: disable lock screen animation:

$> mcetool --set-lockscreen-animation=disabled