Feature: --post-capture-command flag for user-defined upload/processing scripts

Summary

Add a --post-capture-command flag to flameshot gui (and flameshot full/flameshot screen) that executes a user-supplied command after a successful capture, passing the captured image path as an argument. If the command writes a URL to stdout, Flameshot copies it to the clipboard and shows a notification.

This is a small, focused, non-invasive change that unblocks a huge amount of user need without adding any uploader to core — fully consistent with the direction stated in v13.0.0.

Background and motivation

Since v13.0.0 removed the Imgur uploader (intentionally and correctly — it doesn't belong in core), users who want to upload screenshots to self-hosted services like XBackBone, Zipline, Nextcloud, or any custom endpoint have no first-class solution.

The current workaround is to use flameshot gui -r > /tmp/shot.png piped into a shell script bound to a keyboard shortcut — but this bypasses the Flameshot GUI entirely. Users lose annotation tools, the capture preview, and the ability to cancel.

The other workaround — registering a script as a .desktop application and using "Open with…" — requires an extra manual click after every capture. The XBackBone author (@sergix44) commented on PR #955:

"You can use the script in combination with the 'Open with..' of flameshot, but I don't think is a robust system."

Issues tracking this need span years and hundreds of reactions: #499 (2019, 28), #750 (2020), #955 (RFC PR, 2020), #2483, #2529 (plugin RFC), #2555, #3467, #3711 (2024) — all requesting some form of post-capture hook.

Proposed solution

CLI flag

flameshot gui --post-capture-command "COMMAND"

COMMAND is a shell command string. Before execution, Flameshot substitutes:

If no placeholder is present, the path is appended as the final argument.

Examples:

# Upload to XBackBone, copy returned URL to clipboard
flameshot gui --post-capture-command \
  "curl -sF token=MY_TOKEN -F upload=@%f https://xb.example.com/upload | jq -r .url | wl-copy"

# Upload to any ShareX-compatible host
flameshot gui --post-capture-command "~/.local/bin/my-uploader.sh %f"

# Just print the path (useful for testing)
flameshot gui --post-capture-command "echo %f"

Stdout → clipboard behaviour

If the command exits 0 and writes a single non-empty line to stdout, Flameshot treats it as a URL, copies it to the clipboard, and shows a desktop notification: "Screenshot uploaded — URL copied to clipboard".

If the command exits non-zero, Flameshot shows an error notification with stderr truncated to 200 chars.

Config file support (optional, nice-to-have)

# ~/.config/flameshot/flameshot.ini
[General]
postCaptureCommand=~/.local/bin/my-uploader.sh %f

The CLI flag takes precedence over the config file value.

Why not wait for the plugin system?

The plugin RFC (#2529) is the right long-term answer. But it requires converting Flameshot to a shared library, bridging to Python, and designing an entire plugin API — a multi-month effort. --post-capture-command can be implemented in ~150 lines of C++, reviewed in a single PR, and shipped immediately.

It is also complementary to the plugin system: once plugins land, an upload plugin can use the same post-capture hook point internally, and --post-capture-command remains useful for users who just want a quick shell script without writing a plugin.

Implementation sketch

Reference implementation and patch files: https://forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command

A PR will follow pending maintainer response to this issue.

Key touch points (all small):

1. src/cli/commandlineparser.cpp — add QCommandLineOption for post-capture-command / alias pcc
2. src/core/capturerequest.h/.cpp — add postCaptureCommand string field, set from CLI parser; add PostCaptureCommand to the ExportTask bitmask
3. src/core/flameshot.cpp — in the capture-completed signal handler, after all other export tasks, if postCaptureCommand is set: write the pixmap to a temp PNG, substitute %f, launch via QProcess, connect stdout/stderr/finished signals, handle clipboard copy and notifications
4. src/utils/confighandler.h/.cpp — add postCaptureCommand config key

No new dependencies. Uses only Qt classes already in the project (QProcess, QTemporaryFile, QClipboard, QSystemTrayIcon).

Considered alternatives

Related issues and prior art

• #499 — Option to use custom uploaders (28)
• #750 — Custom uploaders
• #955 — RFC for upload plugins (PR, XBackBone author commented)
• #2483 — Custom uploader script discussion
• #2529 — Plugin RFC
• #2555 — Custom action button request
• #3467 — Auto-upload request
• #3711 — Zipline uploader request (2024)
• XBackBone Linux client docs
• Zipline Flameshot guide

Reference implementation

A reference implementation and XBackBone plugin stub are available at: https://forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command