xdg-desktop-portal-termfilechooser

xdg-desktop-portal backend for choosing files with your favorite terminal file manager.

Features

Single file selection
Multi-file selection
Directory selection
Multi-user support
Customizable execution through shell scripts

Installation

Packages

yay -S xdg-desktop-portal-termfilechooser-hunkyburrito-git

NixOS

Building from source

Download source

git clone https://github.com/hunkyburrito/xdg-desktop-portal-termfilechooser

Dependencies

Install the required packages for your distribution.

On apt-based systems:

sudo apt install xdg-desktop-portal build-essential ninja-build meson libinih-dev libsystemd-dev scdoc

On Alpine/postmarketOS:

sudo apk add meson musl-dev ninja-build clang cmake pkgconfig inih-dev basu-dev scdoc xdg-desktop-portal

On Arch-based systems:

sudo pacman -S xdg-desktop-portal libinih ninja meson scdoc git

Build

cd xdg-desktop-portal-termfilechooser
meson build
ninja -C build
ninja -C build install  # run with superuser privileges

Note: Some distributions require termfilechooser.portal to be in /usr/share/xdg-desktop-portal/portals/.

Known distributions that require this are Alpine/postmarketOS, Debian, and Arch Linux.

sudo mv /usr/local/share/xdg-desktop-portal/portals/termfilechooser.portal /usr/share/xdg-desktop-portal/portals/

Configuration

By default, the contents of the contrib folder are placed in /usr/local/share/xdg-desktop-portal-termfilechooser/. Copy the config to $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/ and edit it to set your preferred wrapper and default directory.

The configuration is as follows:

[filechooser]

cmd: The wrapper script/command to run.
create_help_file: Create destination save file with instructions. Must be 0 or 1 (default). See man 5 xdg-desktop-portal-termfilechooser for more info.
default_dir: The default directory to open if the application (e.g. firefox) does not suggest a path.
env: Sets the specified environment variables with the specified values.
- TERMCMD: The environment variable that sets what command to use for launching a terminal.
open_mode: Sets the mode for the starting path when selecting files/directories. Must be one of suggested, default, or last. See man 5 xdg-desktop-portal-termfilechooser for more info.
save_mode: Sets the mode for the starting path when saving files. Must be one of suggested, default, or last. See man 5 xdg-desktop-portal-termfilechooser for more info.

Wrappers specified within the cmd key in the config are searched for in order of the following directories unless the absolute path is specified.

$XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser
/usr/local/share/xdg-desktop-portal-termfilechooser
/usr/share/xdg-desktop-portal-termfilechooser
Any other directory in your $PATH

Setting TERMCMD can be done with the following methods (in recommended order):

Using the env key in the config
Editing the cmd key in the config
Exporting a global TERMCMD environment variable
Creating/Editing your own wrapper file

Examples

Using `env`:

Note: Setting environment variables in the config with env does not require you to quote the entire value. See example below.

### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###

[filechooser]
cmd=yazi-wrapper.sh
default_dir=$HOME
env=TERMCMD=foot -T "terminal filechooser"
    VARIABLE2=VALUE2
open_mode = suggested
save_mode = last

OR

### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###

[filechooser]
cmd=yazi-wrapper.sh
default_dir=$HOME
env=TERMCMD=foot -T "terminal filechooser"
env=VARIABLE2=VALUE2
open_mode = suggested
save_mode = last

Environment variables can also be unset. (e.g. env=VARIABLE=)

Editing `cmd`:

Note: Setting environment variables through prepending requires proper quoting and necessary escaping. See example below.

### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###

[filechooser]
cmd=TERMCMD='foot -T "terminal filechooser"' yazi-wrapper.sh
default_dir=$HOME
open_mode = suggested
save_mode = last

Exporting a global:

Note: Setting TERMCMD globally requires proper quoting and necessary escaping. See example below.

### $HOME/.profile, .bashrc, or equivalent ###

export TERMCMD='foot -T "terminal filechooser"'

Modifying a wrapper:

cp /usr/local/share/xdg-desktop-portal-termfilechooser/yazi-wrapper.sh $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/yazi-wrapper.sh

Make your changes, then:

### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###

[filechooser]
# prioritizes `yazi-wrapper.sh` in `$XDG_CONFIG_HOME` dir over `/usr/local/share` and `/usr/share` dirs
cmd=yazi-wrapper.sh
default_dir=$HOME
open_mode = suggested
save_mode = last

Usage

Launching termfilechooser

Systemd service

The simplest way to use this program is through the provided systemd service. Once installed, it should automatically start running after restarting the xdg-desktop-portal service.

systemctl --user restart xdg-desktop-portal.service

Manual execution

If you encounter issues or prefer launching manually, you can start termfilechooser yourself.

Note: Depending on the installation method the binary could have a different path.

/usr/local/lib/xdg-desktop-portal-termfilechooser -r &

Selection

File(s) selection is pretty straightforward - select and then "open" the files.

Directory selection can vary depending on the file manager, however. Most file managers support selecting directories by entering them and then quitting, but some also support selecting/opening them like file selection.

File Manager	"Quit" Selection	"Open" Selection
lf	yes	no
nnn	yes	yes
ranger	yes	no
vifm	yes	yes
yazi	yes	yes

Note: File managers that use "Quit" Selection often have a keybind or command to abort the selection process. For example, in yazi it is 'Q'.

Tips

Firefox

Firefox has a setting in its about:config to always use XDG desktop portal's file chooser.

Set widget.use-xdg-desktop-portal.file-picker to 1. See the ArchWiki for more information.

Disable the original file picker portal

If your xdg-desktop-portal version (/usr/lib/xdg-desktop-portal --version) is newer than 1.18.0, you can specify the preferred FileChooser in $XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf.

    ### $XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf ###

    [preferred]
    org.freedesktop.impl.portal.FileChooser=termfilechooser

See the flatpak docs and ArchWiki for more information on portals.conf.

If your version is older, you can remove FileChooser from Interfaces of the {gtk;kde;…}.portal files:

find /usr/share/xdg-desktop-portal/portals -name '*.portal' -not -name 'termfilechooser.portal' \
	-exec grep -q 'FileChooser' '{}' \; \
	-exec sudo sed -i'.bak' 's/org\.freedesktop\.impl\.portal\.FileChooser;\?//g' '{}' \;

Troubleshooting

Common issues

Wrapper failure ([ERROR] - filechooser: could not execute ...)

Check that the config is correct, ensuring there is proper escaping if necessary.
Try manually running termfilechooser instead (the systemd service may have issues with getting/setting the environment).
Try updating termfilechooser and restarting the relevant systemd services.

Only some applications work

For GTK applications, try setting the GDK_DEBUG=portals environment variable when running the problematic application. If that doesn't help, try using the deprecated GTK_USE_PORTAL=1 instead.
For electron applications, try using a package built against a newer electron version. Older electron versions do not support the filechooser portal, and some versions have broken support (see electron/electron#43819).
For Qt applications, try setting QT_QPA_PLATFORMTHEME=flatpak or QT_QPA_PLATFORMTHEME=xdgdesktopportal when running the application.

Outdated version

Ensure you are on the most up-to-date version of termfilechooser. The version can be checked by running /usr/local/lib/xdg-desktop-portal-termfilechooser -v (correct path as needed).

Terminal File Manager does not work with "Open/Show Folder" dialogs

This is expected behavior. Currently termfilechooser only works for selecting files and folders for downloading/uploading. Dialogs, like the one mentioned, use a different interface - https://www.freedesktop.org/wiki/Specifications/file-manager-interface.
To get this functionality you can use https://github.com/boydaihungst/org.freedesktop.FileManager1.common

See also: Troubleshooting section in ArchWiki.

If the above do not help, please continue troubleshooting and submit an issue/PR about the problem.

Logs

When termfilechooser runs as a systemd service, it's output can be viewed with journalctl.

journalctl --user -eu xdg-desktop-portal-termfilechooser

The available logging levels in order of increasing verbosity are: QUIET, ERROR, WARN(default), INFO, DEBUG, and TRACE. Running the program manually allows you to change the logging level much easier.

Note: Correct the binary path as necessary.

/usr/local/lib/xdg-desktop-portal-termfilechooser -r -l DEBUG

After running this command, try the problematic actions again and you should see more information on what is going wrong.

Testing

Using zenity can make it easier to quickly test the portal. Remember to restart termfilechooser if you edit the config.

systemctl --user restart xdg-desktop-portal-termfilechooser.service

File selection test:

GDK_DEBUG=portals zenity --file-selection

Multiple file selection test:

GDK_DEBUG=portals zenity --file-selection --multiple

Directory selection test:

GDK_DEBUG=portals zenity --file-selection --directory

Save test:

GDK_DEBUG=portals zenity --file-selection --save --filename=test.txt

Documentation

A man page documenting wrapper script arguments and configuration options is provided. See man 5 xdg-desktop-portal-termfilechooser.

License

MIT

Credits

Original Author: GermainZ

Upstream Author: boydaihungst

Name		Name	Last commit message	Last commit date
Latest commit History 156 Commits
.github		.github
contrib		contrib
include		include
src		src
.clang-format		.clang-format
.editorconfig		.editorconfig
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
meson.build		meson.build
meson_options.txt		meson_options.txt
org.freedesktop.impl.portal.desktop.termfilechooser.service.in		org.freedesktop.impl.portal.desktop.termfilechooser.service.in
termfilechooser.portal		termfilechooser.portal
xdg-desktop-portal-termfilechooser.5.scd		xdg-desktop-portal-termfilechooser.5.scd

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

xdg-desktop-portal-termfilechooser

Table of Contents

Features

Installation

Packages

Building from source

Download source

Dependencies

Build

Configuration

Examples

Using `env`:

Editing `cmd`:

Exporting a global:

Modifying a wrapper:

Usage

Launching termfilechooser

Systemd service

Manual execution

Selection

Tips

Firefox

Disable the original file picker portal

Troubleshooting

Common issues

Logs

Testing

Documentation

License

Credits

About

Uh oh!

Releases 7

Languages

License

hunkyburrito/xdg-desktop-portal-termfilechooser

Folders and files

Latest commit

History

Repository files navigation

xdg-desktop-portal-termfilechooser

Table of Contents

Features

Installation

Packages

Building from source

Download source

Dependencies

Build

Configuration

Examples

Using env:

Editing cmd:

Exporting a global:

Modifying a wrapper:

Usage

Launching termfilechooser

Systemd service

Manual execution

Selection

Tips

Firefox

Disable the original file picker portal

Troubleshooting

Common issues

Logs

Testing

Documentation

License

Credits

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Languages

Using `env`:

Editing `cmd`: