engine internals

wflow:// protocol

wflow registers a wflow:// URL scheme handler so clicking a link in your browser hands off directly to the wflow desktop. Same idea as magnet: for torrents or vscode:// for VS Code.

Schemes

`wflow://import?source=...`

Install a workflow into the local library. The source param is the URL of the workflow's /raw endpoint on wflows.io — the desktop fetches it, parses it, and writes the KDL into ~/.config/wflow/workflows/.

wflow://import?source=https%3A%2F%2Fwflows.io%2Fcush%2Ffocus-mode%2Fraw

Generated automatically by the Open in wflow button on every workflow detail page. Clicking it fires the URL; the OS routes it to the wflow scheme handler; the desktop shows a confirm dialog with the workflow's title, author, description, and step count, then writes to disk when you accept.

The confirm dialog is the security beat — a drive-by page that opens such a URL can't silently install a workflow you didn't intend to keep.

`wflow://auth/callback?nonce=...&token=...`

Used by the desktop sign-in handshake. The desktop opens wflows.io/auth/desktop?nonce=<random> in your browser; after you sign in, the page redirects to this URL. The desktop verifies the nonce, stores the token in state.toml, and shows your handle in the nav.

See the v0 API reference for the full sign-in flow and the polling fallback that handles sessions where the deeplink never arrives.

Single-instance forwarding

Each wflow:// click spawns a fresh wflow %u process via the desktop entry. If the wflow GUI is already running, the new process forwards its URL to the running instance over a Unix socket and exits, so the deeplink lands in your existing window instead of opening a second one.

Browser registration

On first GUI run, wflow writes a per-user .desktop file to ~/.local/share/applications/io.github.cushycush.wflow.desktop with MimeType=x-scheme-handler/wflow;, then registers it as the default handler:

xdg-mime default io.github.cushycush.wflow.desktop x-scheme-handler/wflow
update-desktop-database ~/.local/share/applications

First time you click a wflow:// link, your browser asks whether to allow this site to open the wflow app. Say yes; the browser remembers the choice for that origin.

If the scheme isn't registered

Your browser shows a "no app to handle this URL" error. Fix:

Verify the desktop file exists at ~/.local/share/applications/io.github.cushycush.wflow.desktop
Run xdg-mime query default x-scheme-handler/wflow — it should print io.github.cushycush.wflow.desktop
If not: xdg-mime default io.github.cushycush.wflow.desktop x-scheme-handler/wflow
Refresh: update-desktop-database ~/.local/share/applications
Re-launch wflow once — first run rewrites the desktop file if its Exec= line doesn't match the current binary.

Flatpak ships its own scheme-registered desktop entry; the runtime registration above is skipped inside the sandbox.

Manual install (no scheme)

If for whatever reason you don't want the scheme handler:

Copy the KDL source from any workflow's detail page
Save it to ~/.config/wflow/workflows/<slug>.kdl
The daemon's file watcher picks it up automatically; portal-mode users restart the daemon to apply trigger changes (systemctl --user restart wflow-daemon).

Daemon & systemd →