Name

app — D-Bus application launcher

Synopsis

app --help

app --version

app --list

app APPID

app APPID [FILE...]

app APPID --list-actions

app APPID --action ACTION [PARAMETER]

Description

app is a commandline implementation of the client-side of the org.freedesktop.Application interface as specified by the freedesktop.org Desktop Entry Specification.

app can be used to start applications that have DBusActivatable set to true in their .desktop files.

It is possible for applications to refer to app in the Exec line of their .desktop file to maintain backwards compatibility with implementations that do not directly support DBusActivatable.

app ships as part of GLib.

Commands

Global commands

--help

Displays a short synopsis of the available commands.

--version

Prints the GLib version whence app came.

--list

Prints a list of all application IDs that are known to support D-Bus activation. This list is generated by scanning .desktop files as per the current XDG_DATA_DIRS.

Per-application commands

Excepting the above flags, all invocations of app must have an application ID as the first argument. This is in the familiar "reverse DNS" format, and does not include the .desktop suffix. All operations will be performed on this application.

It is possible for arguments to follow the application ID.

--list-actions

List the actions declared in the application's .desktop file.

--action ACTION [PARAMETER]

Invokes the named action (in the same way as would occur when activating an action specified in the .desktop file). The name of the action must directly follow --action. Optionally, following the action name can be one parameter, in GVariant format, given as a single argument. Ensure sufficient quoting.

If no additional arguments are given following the application ID, the specified application is activated (ie: its main window is shown with no particular file being opened).

If filenames or URIs are specified then those files are opened with the specified application.

Examples

From the commandline

Launching an application:

        app org.example.fooview
      

Opening a file with an application:

        app org.example.fooview ~/file.foo
      

Opening many files with an application:

        app org.example.fooview ~/foos/*.foo
      

Invoking an action on an application:

        app org.example.fooview --action create
      

From the Exec lines of a .desktop file

The commandline interface of app was designed so that it could be used directly from the Exec line of a .desktop file.

You might want to do this to allow for backwards compatibility with implementations of the specification that do not understand how to do D-Bus activation, without having to install a separate utility program.

Consider the following example:

        [Desktop Entry]
        Version=1.1
        Type=Application
        Name=Foo Viewer
        DBusActivatable=true
        MimeType=image/x-foo;
        Exec=app org.example.fooview %F
        Actions=gallery;create;

        [Desktop Action gallery]
        Name=Browse Gallery
        Exec=app org.example.fooview --action gallery

        [Desktop Action create]
        Name=Create a new Foo!
        Exec=app org.example.fooview --action create
      

From a script

If installing an application that supports D-Bus activation you may still want to put a file in /usr/bin so that your program can be started from a terminal.

It is possible for this file to be a shell script. The script can handle arguments such as --help and --version directly. It can also parse other command line arguments and convert them to uses of app to activate the application, open files, or invoke actions.

Here is a simplified example, as may be installed in /usr/bin/fooview:

        #!/bin/sh

        case "$1" in
          --help)
            echo "see 'man fooview' for more information"
            ;;

          --version)
            echo "fooview 1.2"
            ;;

          --gallery)
            app org.example.fooview --action gallery
            ;;

          --create)
            app org.example.fooview --action create
            ;;

          -*)
            echo "unrecognised commandline argument"
            exit 1
            ;;

          *)
            app org.example.fooview "$@"
            ;;
        esac
      

See also

gdbus(1), xdg-open(1), desktop-file-validate(1)