How to use Flameshot with XBackBone on GNU+Linux (fully automatic, no extra clicks)

[LoudLemur]

How to use Flameshot with XBackBone on GNU+Linux (fully automatic, no extra clicks)

If you've migrated from Windows and miss ShareX's one-key capture-and-upload workflow, this guide
gets you there on Linux using Flameshot and your self-hosted
XBackBone instance.

The end result: press a key → Flameshot GUI opens → annotate your screenshot → confirm →
image uploads automatically → URL is in your clipboard → desktop notification appears.
No extra clicks.

---

Why this isn't obvious

Flameshot v13+ deliberately removed its built-in Imgur uploader. The project's stance is that
uploaders don't belong in core — they want a plugin system instead (still in progress). So there's
no settings toggle for "upload to XBackBone". The workaround most people find — XBackBone's
"Open with..." desktop entry — still requires a manual click after every capture.

The approach below is fully automatic using flameshot gui -r, which pipes the captured PNG
directly to a script.

---

Prerequisites

You'll need these installed. Check with which <name>:

• flameshot — screenshot tool (install via your package manager, not Flatpak — see note below)
• curl — HTTP upload
• jq — JSON parsing
• wl-copy — Wayland clipboard (package: wl-clipboard). If you're on X11 use xclip instead.
• notify-send — desktop notifications (usually pre-installed)

Flatpak note: The Flatpak version of Flameshot has sandboxing restrictions that prevent it
running external scripts reliably. Install the native package for your distro instead
(e.g. sudo dnf install flameshot on Fedora/Bazzite, sudo apt install flameshot on Ubuntu/Debian).

---

Step 1 — Get your XBackBone token and URL

Log into your XBackBone instance → click your username (top right) → Profile →
scroll down to Linux Script → download the script.

Open it in a text editor and note:

• The upload URL (e.g. https://xb.yourdomain.com/upload)
• Your token (e.g. token_abc123...)

You only need these two values — you don't need to use the script itself.

---

Step 2 — Create the upload script

Create the file ~/.local/bin/flameshot-xbackbone.sh:

mkdir -p ~/.local/bin
nano ~/.local/bin/flameshot-xbackbone.sh

Paste this, replacing the URL and token with your own:

#!/usr/bin/env bash
# Capture with Flameshot and upload to XBackBone

XBACKBONE_URL="https://xb.yourdomain.com/upload"
XBACKBONE_TOKEN="token_your_token_here"
LOGFILE="$HOME/.local/share/flameshot-xbackbone/upload.log"

mkdir -p "$(dirname "$LOGFILE")"

# Dependency check
for cmd in flameshot curl jq wl-copy notify-send; do
    if ! command -v "$cmd" &>/dev/null; then
        notify-send "flameshot-xbackbone" "Missing dependency: $cmd" -i dialog-error
        exit 1
    fi
done

# Capture
TMPFILE=$(mktemp /tmp/flameshot-XXXXXX.png)
trap 'rm -f "$TMPFILE"' EXIT

flameshot gui -r > "$TMPFILE" 2>/dev/null

# Exit silently if user cancelled
if [[ ! -s "$TMPFILE" ]]; then
    echo "$(date '+%F %T') INFO: cancelled" >> "$LOGFILE"
    exit 0
fi

# Upload (note: field name is 'upload', not 'file')
RESPONSE=$(curl -s \
    -F "token=$XBACKBONE_TOKEN" \
    -F "upload=@$TMPFILE" \
    "$XBACKBONE_URL")

URL=$(echo "$RESPONSE" | jq -r '.url // empty' 2>/dev/null)

if [[ -n "$URL" ]]; then
    printf '%s' "$URL" | wl-copy
    notify-send "Screenshot uploaded" "$URL" -i flameshot -t 6000
    echo "$(date '+%F %T') OK: $URL" >> "$LOGFILE"
else
    ERROR=$(echo "$RESPONSE" | jq -r '.message // "Unknown error"' 2>/dev/null)
    notify-send "Upload failed" "$ERROR" -i dialog-error -t 10000
    echo "$(date '+%F %T') FAIL: $RESPONSE" >> "$LOGFILE"
    exit 1
fi

Make it executable:

chmod +x ~/.local/bin/flameshot-xbackbone.sh

Test it manually first:

~/.local/bin/flameshot-xbackbone.sh

Flameshot should open. Take a screenshot. You should get a notification with the URL
and it should be in your clipboard.

---

Step 3 — Register as a desktop application

Create ~/.local/share/applications/flameshot-xbackbone.desktop:

nano ~/.local/share/applications/flameshot-xbackbone.desktop

Paste:

[Desktop Entry]
Name=Flameshot to XBackBone
Comment=Capture screenshot and upload to XBackBone
Exec=/home/YOUR_USERNAME/.local/bin/flameshot-xbackbone.sh
Icon=flameshot
Type=Application
Categories=Utility;Graphics;
Terminal=false
StartupNotify=false
NoDisplay=true
X-KDE-GlobalAccel-CommandShortcut=true

Replace YOUR_USERNAME with your actual username. Then refresh the desktop database:

update-desktop-database ~/.local/share/applications

---

Step 4 — Bind a keyboard shortcut (KDE Plasma)

Go to System Settings → Shortcuts → Custom Shortcuts.

If you installed to flameshot-xbackbone.desktop as above, the entry
"Flameshot to XBackBone" should already appear. Click it and assign your preferred key.

Recommended: Use Print Screen — but first make sure nothing else owns it:

• Spectacle: System Settings → Shortcuts → System Services → Spectacle → clear any PrtSc binding
• Steam: Steam → Settings → In Game → change screenshot key from PrtSc to F12

If you're on GNOME, go to Settings → Keyboard → Custom Shortcuts and add a new entry
pointing to the full script path.

---

Step 5 — First run (Wayland permission prompt)

The first time you press the shortcut after setting it up, KDE/GNOME may show a
"Allow [app] to take a screenshot?" portal dialog. Click Allow.
This is a one-time Wayland security prompt — it won't appear again.

---

Troubleshooting

Script runs but nothing uploads / "Token not specified" error on large files

This is a known PHP behaviour: when a file exceeds your server's post_max_size,
PHP silently drops all POST fields including the token, returning a misleading error.
The solution is to raise both settings in your server config:

• php.ini: post_max_size = 256M and upload_max_filesize = 256M
• nginx.conf: client_max_body_size 256M;

Both must be set — nginx rejects the request before PHP even sees it if its own limit is hit.

Notification appears but clipboard is empty

You're probably on Wayland but xclip is installed and wl-copy isn't.
The script uses wl-copy by default. Install it:

# Fedora/Bazzite
sudo dnf install wl-clipboard

# Ubuntu/Debian
sudo apt install wl-clipboard

Flameshot GUI doesn't open when pressing the shortcut

Try running the script directly from a terminal first. If that works but the shortcut
doesn't, restart KDE's global shortcut daemon:

kglobalaccel5 --restart 2>/dev/null || systemctl --user restart plasma-kglobalaccel.service

Then try the shortcut again.

Logs

All uploads are logged to ~/.local/share/flameshot-xbackbone/upload.log.

---

Notes

• The XBackBone upload field is named upload, not file — this trips up most generic uploader configs
• XBackBone also returns a raw_url field in the response if you want a direct link to the raw image rather than the preview page
• Logs are kept at ~/.local/share/flameshot-xbackbone/upload.log
• This approach works on any distribution and desktop environment — not just KDE

---

Tested on Bazzite (Fedora-based, KDE Plasma, Wayland) with Flameshot 13.3.0 and XBackBone 3.8.1.