← Back to Home

API

Control Wuse from external apps or automation scripts via URL scheme.

🔗

URL Scheme

The following URLs can be triggered from Shortcuts, Terminal, or any app. Since Wuse 4.1.0 every call must carry the local token as token=:

wuse://connect?token=<api-token>

Connect to the last used node.

wuse://connect?id=123&token=<api-token>

Connect to a saved (previously connected) node #123. If the node is not on this device, connect it once in the app first.

Replace <api-token> with the 64 hex characters stored in ~/.config/wuse/api-token (never paste a real token into a web page or share it). Parameter order does not matter.

🛡️

Who can make Wuse connect

Who can make Wuse connect through wuse://connect Only a program that can read the 0600 token file can add the matching token=; calls without it are rejected with no connection. Can read files as you Cannot read the token file reads local token with token= no or wrong token= match missing or mismatch Token file ~/.config/wuse/api-token mode 0600, owned by you 64 hex characters Your script Shortcut or CLI tool wuse://connect?token=… Web page or other app can open wuse:// links but has no token Wuse 4.1.0+ checks every wuse://connect call token= must equal the local token (constant-time compare) Generate in About → API · DMG reads the file · App Store reads Keychain Connects last node, or ?id=N Rejected no connection, no change logs only the reason
  • Only a program that can read ~/.config/wuse/api-token (mode 0600, owned by you) can add the matching token= and make Wuse connect.
  • A web page or another app can still open wuse:// links, but without the token the call is rejected: no connection, nothing changes, and the log records only the reason category.
  • The DMG version reads the file on every call, so a new token works immediately. The App Store version uses the token generated in its Keychain. Regenerate it in About → API and export the new token file for scripts.
  • Any program running as you outside a sandbox can read the file too, so treat the token like a password.
🔑

Create the token

In Wuse 4.1.1 or later, open About → API and click the generate icon to create, view and copy your token. No Terminal setup command is needed.

Tokens contain 64 random hex characters. The DMG version atomically replaces ~/.config/wuse/api-token using a 0600 temporary file in a 0700 directory. Regenerating immediately invalidates the previous token.

If you create the file yourself, it must be a regular file (not a symlink) owned by you, with mode exactly 0600 (fix it with chmod 600), containing exactly 64 hex characters and at most one trailing newline. Anything else is rejected.

⚠️ Use the token only with Wuse 4.1.0 or later. Older versions wrote the full incoming URL, token included, to the system log.

⌨️

Use it from a script

Read the token file at call time instead of pasting the token into a script or Shortcut:

open "wuse://connect?id=123&token=$(cat ~/.config/wuse/api-token)"

Works in Terminal and in the Shortcuts “Run Shell Script” action. $(cat …) drops the trailing newline and leaves the 64-character token; rotating the token needs no script change.

💻

DMG and App Store versions

DMG (downloaded from this site)

Generate, copy or regenerate in About → API. Every call reads ~/.config/wuse/api-token again, so rotation takes effect immediately. Existing valid tokens are preserved.

App Store

Generate in About → API and store the token in the Keychain (not synced). Previously imported tokens are preserved. Click the save icon and confirm the system Save panel once to export to ~/.config/wuse/api-token for scripts. Authorization uses the Keychain token; export the new file again after regeneration.

⛔

When the token is missing or wrong

If the URL has no token=, the token does not match, the token file is missing or invalid, or the App Store version has not generated a token yet, the call is rejected: no connection is made and nothing changes. The app log records only the reason category (for example token_file_wrong_mode), never the URL or the token.

⚙️

Enable

For security, API calls are off by default. Turn it on in the app:

About → API tab → enable “Allow API Call”.

This switch is stored on this Mac only and is not synced to your other Macs.