yourls-ui

Small Qt tray utility for shortening URLs using the YOURLS API.

The application sits in the system tray and allows quickly shortening the URL currently stored in the clipboard.

It was designed as a lightweight helper for everyday use with a self-hosted YOURLS instance.

---

Features (v0.1)

• System tray application
• Simple configuration window
• Uses YOURLS API with signature authentication
• Reads URL from clipboard
• Generates a short URL
• Copies the short URL back to clipboard
• Shows popup with clickable link
• Error reporting with API response

---

How it works

1. Application starts
2. If configuration exists → it goes directly to the system tray
3. If configuration is missing → settings window opens

From the tray menu you can run:

Cut URL

The application will:

1. Read the current clipboard
2. Check if the content is a valid URL
3. Call the YOURLS API
4. Receive a shortened link
5. Copy the shortened link back to clipboard
6. Show a popup window with the result

If YOURLS returns HTTP 400 with error:url and an existing short link for the same source URL, the application uses that link as a successful result.

On Wayland, Cut URL opens a small window when the application is inactive. Activate it to allow clipboard access; the URL is read automatically once the clipboard becomes available. You can also click Read clipboard, or cancel. The result window copies the short URL after gaining focus and displays whether the copy succeeded. Clicking OK retries and verifies the copy before closing.

---

Configuration

The settings window contains:

API URL
API signature

Example:

API URL:
https://example.com/yourls-api.php

Signature:
ABC123

⚠️ Important:

The signature field must contain only the signature value, not:

signature=ABC123

Correct:

ABC123

---

Tray menu

Right click the tray icon to access the menu:

Cut URL
Help
About
Exit

Double clicking the tray icon opens the settings window.

---

Building

Requirements:

Qt 6
Qt Widgets
Qt Network
qmake from Qt 6 (qmake6 on this system)
C++17 compiler

Build:

mkdir -p build-qt6
cd build-qt6
qmake6 ../yourls-ui.pro
make

The Qt 6 qmake executable may be named qmake on other systems; check its version with qmake -v before building.

Or open yourls-ui.pro in Qt Creator, select a Qt 6 kit and use a new build directory separate from any existing Qt 5 build.

---

Debugging clipboard URLs

Build and run a debug executable from a terminal:

mkdir -p build/Desktop-Debug
cd build/Desktop-Debug
qmake6 ../../yourls-ui.pro CONFIG+=debug CONFIG-=release
make
./yourls-ui 2>clipboard-debug.log

Exit any already running instance before starting this executable. Choose Cut URL and inspect clipboard-debug.log. Debug builds log the executable path, Qt platform, clipboard MIME formats, raw text and its UTF-8 hex bytes, parsed URL, request stage, HTTP status and API status. The API signature and full request query are not logged. Clipboard diagnostics may contain private URLs; review the log before sharing it. These diagnostics are compiled out of release builds using QT_NO_DEBUG.

---

Project structure

main.cpp
    Application entry point

mainwindow.h / mainwindow.cpp
    Main application window
    Tray integration
    UI logic

mainwindow.ui
    Qt Designer UI for settings window

yourlsclient.h / yourlsclient.cpp
    YOURLS API client
    Handles HTTP requests and responses

The YOURLS API communication is encapsulated in YourlsClient.

---

API call

The application performs a request similar to:

GET /yourls-api.php
?action=shorturl
&format=json
&signature=<signature>
&url=<url>

Example:

https://example.com/yourls-api.php?action=shorturl&format=json&signature=ABC123&url=https://example.com

---

Future ideas

Possible improvements for future versions:

Hotkey support

Global hotkey to trigger URL shortening.

Clipboard watcher

Automatically detect URLs copied to clipboard.

Tray notifications

Use system notifications instead of popup dialog.

Recent history

Store last shortened URLs.

Custom alias

Allow specifying custom short URL alias.

Open YOURLS admin

Add tray menu entry for opening YOURLS admin panel.

Packaging

Provide:

AppImage
.deb package

---

Version

v0.1

Initial working release.

---

Author

deeaitch

---

License

GPL