I have an alias for okular installed with flatpak that is set up like this:

alias okular="org.kde.okular"

It opens up okular from the terminal. However if I try to open a file from the terminal with that alias e.g:

okular document.pdf

Then it doesn't work. What am I doing wrong?

Is there a way to open a file in the terminal using okular flatpak, rather than using the GUI?


So I found this link:

--file-forwarding If this option is specified, the remaining arguments are scanned, and all arguments that are enclosed between a pair of '@@' arguments are interpreted as file paths, exported in the document store, and passed to the command in the form of the resulting document path. Arguments between '@@u' and '@@' are considered uris, and any file: uris are exported. The exports are non-persistent and with read and write permissions for the application.

Surely this doesn't mean the only way to open files in the terminal using okular flatpak is to do something like this:

flatpak run okular.kde.org --file-forwarding @/home/user/documents/document.pdf@

I can't do this for every pdf I want to open. How can I add this as an alias so that I dont't need to type very long commands when opening different pdfs?

4 Answers 4


A shell function that calls flatpak in the way that you show, and adds @ before and after the given (single) argument (untested as I don't run flatpak):

okular () {
    flatpak run org.kde.okular --file-forwarding "@$1@"

This would be put wherever you put your ordinary aliases, and you would use it as

okular /home/user/documents/document.pdf

on the command line.

To make the function take an arbitrary number of arguments, you would use something like

okular () {
    for arg do
        set -- "$@" "@$arg@"

    flatpak run org.kde.okular --file-forwarding "$@"

The loop adds @ to the beginning and end of each command line argument.

This would enable you to use it as

okular *.pdf

The examples are slightly off, here is what it should look like (using Firefox here):

flatpak run --file-forwarding org.mozilla.firefox @@ file.pdf @@

The path can be relative; the document should be self-contained (this won't work with some saved HTML pages).


After experimenting with the existing answers, it looks like the proper approach is to put the leading and trailing @@ as their own arguments and use a single pair around all file arguments.

flatpak run --file-forwarding okular.kde.org @@ *.pdf @@

Furthermore, @@u will translate filesystem paths into file:// URLs so, if you've got an application which accepts both (eg. a Flatpak'd copy of Firefox or Ungoogled Chromium, then use @@u "$@" @@ in your wrappers.

Here's a proof of concept that I incorporated into my script for generating launcher wrappers for my Flatpak apps:

# Add this to the end of your $PATH

# Remove any stale launch scripts
rm -f "$BIN_DIR"/*
mkdir -p "$BIN_DIR"

for X in $(flatpak list --columns=ref); do
    app_command="$(flatpak info -m "$X" | grep command= | cut -d= -f2)"

    if [ -n "$app_command" ]; then
        # Unset LD_PRELOAD to silence gtk-nocsd errors and support file
        # forwarding so you can sandbox browsers and still open local files
        printf '#!/bin/sh\nunset LD_PRELOAD\nexec flatpak run --file-forwarding "%s" @@u "$@" @@' "$X" >"$cmd_path"
        chmod +x "$cmd_path"

As the caveats list on the gist version says, it's not perfect because you have to choose between refusing URLs or having local paths force-converted to file:// URLs, but it works for the apps I have.

(The proper solution would be to rewrite the wrapper generator in something like Python or Rust and have it parse the Exec keys in the associated .desktop files to figure out what each application wants.)


Well… you already found the solution.

As for the alias, that is a standard Linux thing (i.e. not related to flatpak), so this should work:

alias okular='echo flatpak run okular.kde.org --file-forwarding'

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .