New flatpak command line

Today I released version 0.6.13 of flatpak which has a lot of nice new features. One that I’d like to talk a bit about is the new command line argument format.

The flatpak command line was always a bit low-level and hard to use. Partly this was because of lack of focus on this, and partly due to the fact that the expected UI for flatpak for most people would be a graphical user interface like gnome-software. However, with this new release this changed, and flatpak is now much nicer to use from the commandline.

So, what is new?

Flatpakrepo files

Before you can really use flatpak you have to configure it so it can find the applications and runtimes. This means setting up one or more remotes. Historically you did this by manually specifying all the options for the remote as arguments to the flatpak remote-add command. To make this easier we added a file format (.flatpakrepo) to describe a remote, and made it easy to use it.

The new canonical example to configure the gnome stable repositories is:

$ flatpak remote-add --from gnome \
$ flatpak remote-add --from gnome-apps \

Alternatively you can just click on the above links and they should open in gnome-software (if you have new enough versions installed).

Multiple arguments to install/update/uninstall

Another weakness of the command line has been that commands like install, uninstall and update only accepted one application name argument (and optionally a branch name). This made it hard to install multiple apps in one go, and the separate branch name made it hard to cut-and-paste from output of e.g. flatpak list.

Instead of the separate branch name all the commands now take multiple “partial refs” as arguments. These are partial versions of the OSTree ref format that flatpak uses internally. So, for an internal reference like app/org.gnome.gedit/x86_64/stable, one can now specify one of these:


And flatpak will automatically fill in the missing part in a natural way, and give a detailed error if you need to specify more details:

$ flatpak install gnome org.gnome.Platform
error: Multiple branches available for org.gnome.Platform, you must specify one of: org.gnome.Platform//3.20, org.gnome.Platform//3.22, org.gnome.Platform//3.16, org.gnome.Platform//3.18

Automatic dependencies

The other problem with the CLI has been that it is not aware of runtime dependencies. To run an app you generally had to know what runtime it used and install that yourself. The idea here was that the commandline should be simple, non-interactive and safe. If you instead use the graphical frontend it will install dependencies interactively so you can control where things get installed from.

However, this just made the CLI a pain to use, and you could easily end up in situations where things didn’t work. For instance, if you updated gedit from 3.20 to 3.22 it suddenly depended on a new runtime version, and if you weren’t aware of this it probably just stopped working.

Of course, we still can’t just install dependencies from wherever we find them, because that would be a security issue (any configured remote can supply a runtime for any applications). So, the solution here is for flatpak to become interactive:

$ flatpak update org.gnome.gedit
Looking for updates...
Required runtime for org.gnome.gedit/x86_64/stable (org.gnome.Platform/x86_64/3.22) is not installed, searching...
Found in remote gnome, do you want to install it? [y/n]: y
Installing: org.gnome.Platform/x86_64/3.22 from gnome
Installing: org.gnome.Platform.Locale/x86_64/3.22 from gnome
Updating: org.gnome.gedit/x86_64/stable from gnome-apps
Updating: org.gnome.gedit.Locale/x86_64/stable from gnome-apps

If you have remotes you never want to install dependencies from, you can install them with --no-use-for-deps, and they will not be used. Flatpakrepo files for app-only repositories should set NoDeps=true.

Note that this is not a package-system-like dependency solver that can solve sudoku. It is still a very simple two-way split.

Flatpakref files

The primary way Flatpak is meant to be used is that you configure a few remotes that has most of the applications that you use, then you install from these either on the command line, or via a graphical installer. However, sometimes it is nice to have a single link you can put on a website to install your application. Flatpak now supports that via .flatpakref files. These are very similar to flatpakrepo files, in that they describe a repository, but they additionally contain a particular application in that repository which will be installed.

Such files can be installed by just clicking on them in your web-browser (which will open them for installation in gnome-software) or on the command line:

flatpak install --from

This will try to install the required runtime, so you first need to add the remote with the runtimes.

Launching runtimes

During development and testing it is often common to launch commands in a sandbox to experiment with how the runtime works. This was always possible by running a custom command in an application that used the runtime, like so:

$ flatpak run --command=sh org.gnome.gedit
sh-4.3$ ls /app
bin lib libexec manifest.json share

You can even specify a custom runtime with --runtime. However, there really should be no need to have an application installed to do this, so the new version allows you to directly run a runtime:

$ flatpak run org.gnome.Platform//3.22
sh-4.3$ ls /app

10 thoughts on “New flatpak command line”

  1. In the “flatpak install gnome org.gnome.Platform” example, could flatpak sort the matching branches by version? A seemingly random order like 3.20, 3.22, 3.16, 3.18 is confusing and you have to read the whole list to find out if a certain version is present. I know that sorting by version number isn’t exactly trivial, but even a simple lexicographic sort would IMHO be an improvement.

  2. > we still can’t just install dependencies from wherever we find them, because that would be a security issue

    I admit I haven’t taken the time to learn about flatpak/snap/etc. yet, but I was under the impression that these technologies were supposed to offer greater security (than traditional package managers) in the face of untrustworthy sources. Something about containers probably, isn’t everything these days? Sigh.

    Was I wrong?

    [WORDPRESS HASHCASH] The poster sent us ‘0 which is not a hashcash value.

    1. Flatpak (as well as docker, snappy, containers, etc) are about several things. One is security, allowing you to run applications in a sandboxed fashion. Another is distribution, where the isolation from the host filesystem allows you to run an application and its dependencies in way that lets it work independent on what distribution and version you’re running for the main os.

      For ideal use the two combine, so that you get a sandboxed, cross-distro application. However, you can also opt out of parts of the sandbox to only use the distribution side. This is actually what most people are doing right now, as applications typically need to be modified to run heavily sandboxed, and they just aren’t yet.

      In this particular case the security issue is this: I want to play some game, so i add a remote that has the game and install But unknown to me that repository also ships a modified version of a common runtime, say org.freedesktop.Platform. If that was automatically installed, then some *other* application, which may have less secure permissions than the game, could start running code that it didn’t expect to.

      1. I see, that’s mildly disappointing, to be honest. But, thanks for the answer!

        > However, you can also opt out of parts of the sandbox

        Is the user properly notified about exactly what guarantees flatpak is providing for each particular “package” installation?

        [WORDPRESS HASHCASH] The poster sent us ‘0 which is not a hashcash value.

        1. There is code in the library to preview the permissions requested by the application, but its not yet show to the user. Its also possible as a user to override these requests, but that is only exposed to the user in the manual “flatpak override” command. Clearly this part needs more work.

  3. i am a devop using docker and appimage ( I am reading about flatpak and would want to use flatpak, but i have two fundamental challenges regarding flatpak:

    (1) all your and all the examples in internet are just way too much focussed on gnome apps or GUI apps. I agree they are important. But what about terminal based apps??

    Regarding terminal apps, i hardly see any example recipe, except the hello world app.
    “Please publish one real world flatpak recipe bundling a heavily popular real world terminal app” , for example bundling “pandoc” as flatpak.

    (2)how to run multiple terminal programs installed in the same single flatpak app.

    If i want to not bundle jdk as runtime, but the jdk itself as app (say: jdk is an app for developers, though jdk may be platform for layusers). Then say, i have installed jdk as flatpak app, then can i run “java”,”javac”,”jar” etc commands of that app from “the same single flatpak app installation”.

    (3) there is virtually no real world “practical example” of using flatpak to “run a daemon” for a popular program. Say, for example: “postgresql” daemon running as flatpak.

    1. It’s technically possible to run command line apps and services from a flatpak, but it’s not really a focus for flatpak, which is why it’s not demoed much.

Leave a Reply

Your email address will not be published. Required fields are marked *