GAPPLICATION(1)

📦
version 2.90.1 · 10 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

💖 gapplication — the D-Bus application launcher bestie 💖

ok so this is the manual for gapplication(1), which lives in the gapplication() section of your man pages. it's a whole mood and it's genuinely useful, no cap. let's get into it 🫶

✨ NAME ✨

gapplication — D-Bus application launcher 🌸

✨ SYNOPSIS ✨

gapplication help [COMMAND]
gapplication version
gapplication list-apps
gapplication launch <APP-ID>
gapplication launch <APP-ID> [FILE…]
gapplication list-actions <APP-ID>
gapplication action <APP-ID> <ACTION> [PARAMETER]

✨ DESCRIPTION ✨

okay so real talk: gapplication is a commandline implementation of the client-side of the org.freedesktop.Application interface, as specified by the freedesktop.org Desktop Entry Specification. iconic behaviour honestly 👑

you can use gapplication to start up applications that have DBusActivatable set to true in their .desktop files — and it can also send messages to instances of other applications that are already running. like, sliding into their DMs, but for D-Bus 💅

and here's the cute part: applications can literally refer to gapplication in the Exec line of their .desktop file, to maintain backwards compatibility with implementations that do not directly support DBusActivatable. periodt.

gapplication ships as part of GLib 🎀

✨ COMMANDS ✨

  • help [COMMAND] — shows you a short synopsis of the available commands, or if you pass a COMMAND, it gives you the detailed help for that specific command. your little study buddy fr fr 📚
  • version — prints the GLib version whence gapplication came. like, its origin story. its lore ✨
  • list-apps — prints a list of all application IDs that are known to support D-Bus activation. this list gets generated by scanning .desktop files as per the current XDG_DATA_DIRS. slay, go off 🔥
  • launch <APP-ID> [FILE…] — launches an application. 🚀

the first parameter is the application ID in the familiar ‘reverse DNS’ style (e.g. org.gnome.app) without the .desktop suffix. okay bestie, don't forget that part.

optionally, if you give it additional parameters, they get treated as the names of files to open, and they may be filenames or URIs. if no files are given, then the application is simply activated. no files, no problem 💖

  • list-actions <APP-ID> — lists the actions declared in the application's .desktop file. the parameter is the application ID, same as above. it's giving receipts 🧾
  • action <APP-ID> <ACTION> [PARAMETER] — invokes the named action (in exactly the same way as would occur when activating an action specified in the .desktop file). 🎬

the application ID (as above) is the first parameter. the action name follows it.

optionally, following the action name, you can put one parameter, in GVariant format, given as a single argument. make sure to use sufficient quoting — this is the part where everyone messes up, so be careful 🫠

🌈 EXAMPLES 🌈

💻 From the commandline

launching an application:

gapplication launch org.example.fooview

opening a file with an application:

gapplication launch org.example.fooview ~/file.foo

opening many files with an application:

gapplication launch org.example.fooview ~/foos/*.foo

invoking an action on an application:

gapplication action org.example.fooview create

invoking an action on an application, with an action:

gapplication action org.example.fooview show-item '"item_id_828739"'

📝 From the Exec lines of a .desktop file

the commandline interface of gapplication was designed so that it could be used directly from the Exec line of a .desktop file. yes, it was built for this. main character energy 👑

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 — and the best part is you don't have to install a separate utility program to pull it off. we love an efficient queen 💅

consider the following example:

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

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

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

🐚 From a script

if you're 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. totally valid, bestie 🫶

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 gapplication to activate the application, open files, or invoke actions. multitasking icon 💅

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)
    gapplication action org.example.fooview gallery
    ;;

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

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

  *)
    gapplication launch org.example.fooview "$@"
    ;;
esac

✨ SEE ALSO ✨

🎀 and that's the whole page, bestie!! every command, every parameter, every example — all accounted for, no skips, we ate and left no crumbs.

okay bye ily, go launch something gorgeous 💖✨🦋🌸💅👑🌈⭐🍓🧚💜

this has been gapplication(1) — the gapplication() page, shipping as part of GLib 🫶

📦 where this page comes from