This documents a working setup to open Clip Studio Assets links (``clipstudio:…``) on Linux when Clip Studio is installed inside Bottles (Flatpak). When you click the Download button on assets.clip-studio.com, the browser launches a ``clipstudio:assets.clip-studio.com/materialdownload/…`` URL. This handler forwards the URL into the Bottle so Clip Studio downloads the asset.

• Linux desktop with xdg/gio
• Bottles (Flatpak): ``com.usebottles.bottles``
• A Bottle named: Clip Studio
• Clip Studio installed in that bottle
• Programs visible in the bottle (example output):
  • ``CLIPStudio``
  • ``CLIPStudioPaint``

Check your current default handler:

xdg-mime query default x-scheme-handler/clipstudio
gio mime x-scheme-handler/clipstudio

Test a manual open:

gio open "clipstudio://test"

List Bottles programs:

flatpak run --command=bottles-cli com.usebottles.bottles programs -b "Clip Studio"

We install:

• ``/usr/bin/clipstudio-handler`` (desktop entry target)
• ``/usr/bin/clipstudio-worker`` (does the Bottles/Wine forwarding)
• ``/usr/share/applications/clipstudio-handler.desktop`` (registers ``x-scheme-handler/clipstudio``)

The handler debounces rapid clicks and avoids spawning endless Bottles sessions.

If you already have working files installed under ``/usr/local``:

• ``/usr/local/bin/clipstudio-handler``
• ``/usr/local/bin/clipstudio-worker``
• ``/usr/local/share/applications/clipstudio-handler.desktop``

You can build a Debian package that installs them to proper system locations under ``/usr``.

nano ~/build-clipstudio-handler-deb.sh
chmod +x ~/build-clipstudio-handler-deb.sh
~/build-clipstudio-handler-deb.sh

(See the build script in the project notes; it copies from /usr/local into a staging tree and runs dpkg-deb.)

sudo dpkg -i ~/clipstudio-scheme-handler_1.0.0_all.deb
 
sudo dpkg -r clipstudio-scheme-handler

After install/remove, refresh desktop DB if needed:

sudo update-desktop-database /usr/share/applications

Refresh desktop database:

sudo update-desktop-database /usr/share/applications
gio mime x-scheme-handler/clipstudio

Find and kill stuck runs:

pgrep -fa 'bwrap --args .*bottles-cli' || echo "clean"
# kill specific PIDs shown:
kill <PID1> <PID2>
kill -9 <PID1> <PID2> 2>/dev/null || true

This usually indicates the handler is spawning multiple instances or the worker lock is held too long. Verify logs:

tail -n 200 ~/.cache/clipstudio/handler.log
tail -n 200 ~/.cache/clipstudio/worker.script.log

• ``clipstudio:`` URLs contain short-lived login tokens. Avoid pasting them publicly. * The handler should prefer forwarding the URL into the already-running Clip Studio session. </text>