Flameshot upstream contribution

Post-capture command support + XBackBone plugin stub

─────────────────────────────────────────────────────────────────────────────

Overview

This folder contains everything needed to make a meaningful upstream contribution to Flameshot that solves the "upload to self-hosted service" problem permanently, without adding any uploader to core.

The contribution has two parts:

1. --post-capture-command flag — a focused C++ change that lets users run any shell command after capture. ~150 lines, no new dependencies, directly addresses issues #499, #750, #2555, #3467, #3711.

2. XBackBone plugin stub — a forward-looking Python plugin for the plugin system being designed in Discussion #2529. Gives the plugin system designers a real-world use case to design against, and gives XBackBone users a starting point the moment the system ships.

---

Files and what to do with them

GitHub posts

File	Action
GITHUB_RFC_ISSUE.md	Open https://github.com/flameshot-org/flameshot/issues/new — paste title and body from this file. Post BEFORE the PR to gauge maintainer interest.
GITHUB_PR_DESCRIPTION.md	Open the PR after forking and implementing. Paste as the PR description. Fill in the fork URL and PR URL placeholders.

Recommended order: Post the RFC issue first. Wait for a maintainer response. If they're receptive, open the PR. If they want changes to scope, adjust before implementing.

---

C++ implementation patches

These are annotated patch files, not diffs — each one explains exactly where in the source to add the code. Fork https://github.com/flameshot-org/flameshot, clone locally, and apply each patch:

File	Target in Flameshot source
src/cli/commandlineparser.h.patch	src/cli/commandlineparser.h
src/cli/commandlineparser.cpp.patch	src/cli/commandlineparser.cpp
src/core/capturerequest.h.patch	src/core/capturerequest.h
src/core/capturerequest.cpp.patch	src/core/capturerequest.cpp
src/core/flameshot.cpp.patch	src/core/flameshot.cpp (main logic)
src/core/confighandler.patch	src/utils/confighandler.h + .cpp

Build with the standard Flameshot CMake procedure:

cmake -S . -B build && cmake --build build

Test the flag manually:

# Should open Flameshot GUI; after capture, print path and copy URL
./build/src/flameshot gui --post-capture-command \
  "curl -sF token=YOUR_TOKEN -F upload=@%f https://xb.haggis.top/upload | jq -r .url"

---

XBackBone plugin

File	Purpose
plugins/xbackbone/NOTES.md	XBackBone API gotchas — read before implementing any XBackBone client. Covers token-not-specified on large files, 413 from nginx, Wayland clipboard, SSL, token rotation.
plugins/xbackbone/__init__.py	Full plugin stub. Upload logic is production-ready. Plugin scaffolding (base classes, registration) is forward-looking and will need adjusting to match the actual plugin API when it ships.

Where to post the plugin stub: Once the Flameshot plugin system RFC (#2529) has maintainer traction, open a discussion or PR on https://github.com/flameshot-org/plugins offering this as a reference implementation. Reference the NOTES.md as evidence that real-world XBackBone clients have non-obvious requirements worth baking into plugin helpers (e.g., a notify_with_url_clipboard() helper that handles Wayland vs X11).

---

Sequencing recommendation

1. Read plugins/xbackbone/NOTES.md — understand the XBackBone API
2. Post the RFC issue (GITHUB_RFC_ISSUE.md) — wait for response
3. Fork Flameshot, apply the C++ patches, build and test
4. Open the PR (GITHUB_PR_DESCRIPTION.md) — fill in fork/PR URLs
5. Watch Discussion #2529 — when the plugin system moves forward, offer plugins/xbackbone/__init__.py as a reference plugin

---

Key context for reviewers

• v13.0.0 deliberately removed Imgur — any new uploader in core will be rejected
• The --post-capture-command approach is explicitly supported by the v13 release notes: "When [the plugin system] is completed, users who wish to have an uploader right in their screenshot program can implement this in a plugin" — this flag is the bridge until then
• The XBackBone author commented on PR #955 calling the "Open with…" workaround "not a robust system" — this directly addresses that concern
• Issues requesting this span 2019–2024 with hundreds of 👍 reactions combined