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

[LoudLemur]

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 → 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 approach below uses flameshot gui -r which pipes the captured PNG to a shell script,
keeping the full Flameshot GUI (annotation tools, preview, cancel) intact.

---

Prerequisites

You'll need these installed:

• flameshot — native package only, not Flatpak (Flatpak sandboxing prevents running external scripts)
• curl — HTTP upload
• jq — JSON parsing
• wl-copy — Wayland clipboard (package: wl-clipboard). X11 users: use xclip instead
• notify-send — desktop notifications (usually pre-installed)
• xbindkeys — key binding daemon (see Step 4)

# Fedora / Bazzite
sudo dnf install flameshot curl jq wl-clipboard xbindkeys

# Ubuntu / Debian
sudo apt install flameshot curl jq wl-clipboard xbindkeys

---

Step 1 — Get your XBackBone token

Log into your XBackBone instance → click your username → Profile → scroll to
Linux Script → note the upload URL and token value.

---

Step 2 — Create the upload script

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

#!/usr/bin/env bash
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")"

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

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

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

if [[ ! -s "$TMPFILE" ]]; then
    exit 0  # user cancelled — silent exit
fi

# Note: field name is "upload" not "file", token sent first (see troubleshooting)
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

chmod +x ~/.local/bin/flameshot-xbackbone.sh
# Test it manually first
~/.local/bin/flameshot-xbackbone.sh

---

Step 3 — First run: Wayland permission prompt

On the first capture, KDE/GNOME may show: "Allow [app] to take a screenshot?" — click Allow.
This is a one-time Wayland portal prompt. It won't appear again.

---

Step 4 — Keyboard shortcut via xbindkeys

Why not KDE Custom Shortcuts?

KDE Plasma 6 removed khotkeys, the daemon that powered custom shortcuts. The UI still exists
but the daemon does not ship on Fedora-based systems. KDE's alternative service shortcut
mechanism (kglobalacceld) works for system services but is unreliable for user scripts.
On Wayland, Plasma's compositor also intercepts PrtSc and common modifier combinations
(Ctrl+PrtSc, Meta+PrtSc) before the shortcut system sees them.

xbindkeys is a standalone daemon that bypasses KDE's shortcut infrastructure entirely.
It just works.

# Create the xbindkeys config
cat > ~/.xbindkeysrc << 'EOF'
"/home/YOUR_USERNAME/.local/bin/flameshot-xbackbone.sh"
  control + Pause
EOF

# Start it now (no reboot needed)
xbindkeys

# Verify
pgrep xbindkeys

Recommended key: Ctrl+Pause — nothing in KDE, Steam, Spectacle, or NVIDIA intercepts
the Pause key. PrtSc variants will be grabbed by Plasma's compositor on Wayland.
If you prefer a different key, use xbindkeys --key to get the key name interactively.

Autostart xbindkeys on login

cat > ~/.config/autostart/xbindkeys.desktop << 'EOF'
[Desktop Entry]
Name=xbindkeys
Exec=xbindkeys
Type=Application
Terminal=false
StartupNotify=false
X-KDE-AutostartPhase=1
EOF

---

Troubleshooting

"Token not specified" error on large screenshots

This is a PHP behaviour: when a file exceeds post_max_size, PHP silently drops all POST fields
including the token, returning a misleading error. Fix on your server:

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

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

Clipboard is empty after upload

You're on Wayland but using xclip instead of wl-copy. Install wl-clipboard:

sudo dnf install wl-clipboard   # Fedora/Bazzite
sudo apt install wl-clipboard   # Ubuntu/Debian

Flameshot doesn't open when shortcut is pressed

Test the script directly from a terminal first. If that works, check xbindkeys is running:

pgrep xbindkeys || xbindkeys

Logs

cat ~/.local/share/flameshot-xbackbone/upload.log

---

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

Full write-up including a tour of every failed KDE shortcut approach:
wanderingmonster.dev/blog/flameshot-xbackbone-linux

Reference implementation and upstream RFC:
forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command