Driving CleanShot X via the cleanshot:// URL scheme

CleanShot X is a macOS screenshot and screen-recording app from MagicLasso. It exposes a URL scheme (cleanshot://command?param=value&…) that triggers any of its capture, recording, OCR, annotation, pin, history, or settings actions. Opening such a URL launches the app (if needed) and runs the action. That URL scheme is the only supported automation surface — there is no public CLI, AppleScript dictionary, or HTTP API. macOS Shortcuts.app actions internally invoke the same scheme.

The full per-command reference with every parameter and version constraint lives in references/url-scheme.md. Read it before automating any command this SKILL.md does not show in full.

Gotchas — read these before automating

• Requires an Aqua login session. open "cleanshot://…" goes through LaunchServices and the app's UI. It needs an active logged-in graphical session for the same user — over SSH it fires only when that user is also logged in locally. It will not run from a launchd Background agent or before login. Use a user-context launchd agent (LimitLoadToSessionType: Aqua), Screen Sharing, or run it as a step inside a logged-in session.
• CleanShot X must be installed and able to launch. If the app is not installed, opening the URL silently does nothing or prompts the user to choose an app. Verify with mdfind "kMDItemCFBundleIdentifier == 'pl.maketheweb.cleanshotx'", or check the common install paths: /Applications/CleanShot X.app (direct/App Store) and ~/Applications/Setapp/CleanShot X.app (Setapp).
• No return value, no completion signal. The URL fires asynchronously; the calling shell gets exit code 0 as soon as open hands off. There is no built-in way to wait for "capture finished" or to recover the resulting file path. To know what happened: inspect the configured save folder (CleanShot ▸ Settings ▸ Screenshots ▸ "Save to") or watch the clipboard.
• URL parameters must be URL-encoded. Spaces in a filepath become %20. Always quote the URL when passing it to open, and percent-encode user-supplied paths. See the helper at the bottom of this file.
• Version-gated parameters may not work on older builds. Parameters added in 4.7 (action=…, x/y/width/height/display on most commands, start=true, autoscroll=true, tab=…) are not supported on earlier versions and are typically ignored — the command still runs without the parameter. Don't rely on a version-gated parameter without first checking defaults read "/Applications/CleanShot X.app/Contents/Info" CFBundleShortVersionString.
• action is a single value, not a chain. action=annotate alone is valid; action=copy,upload is not. Pick one of copy | save | annotate | upload | pin. To compose actions (e.g. annotate then upload), drive subsequent steps from a follow-up URL or from the annotator UI.
• filepath parameter rules. When you supply a filepath to any command that takes one (pin, open-annotate, capture-text, add-quick-access-overlay), it must be an absolute path — not ~-relative. Expand ~ in the shell before passing. The parameter is optional for pin / open-annotate / capture-text (omitting it falls back to an interactive picker or area selection — see references/url-scheme.md) and required for add-quick-access-overlay. Accepted formats: PNG and JPEG for screenshot commands; add-quick-access-overlay additionally accepts MP4.
• Apple-backend / sandbox surprises. Capturing a window or area may require Screen Recording permission for the app. Recording the screen also requires Microphone permission if audio is enabled. The first run of any command may surface a TCC prompt that needs a user click — agents cannot auto-accept TCC.
• scrolling-capture only proceeds with start=true on 4.7+; without it the user has to click "Start" in the overlay. Use start=true&autoscroll=true for a fully unattended capture (4.7+).
• record-screen does not stop itself. There is no stop-recording URL. Stop recording from the menu-bar item, the global shortcut (default ⌘⇧⌥3 stop, or click the floating control), or by sending a cleanshot://record-screen toggle — but the toggle behavior depends on the user's settings and is not guaranteed. Treat recording as user-supervised.
• display= is a 1-based index of the display ordering CleanShot sees. Display 1 is typically the main display; multi-display indices may not match system_profiler SPDisplaysDataType ordering. Test on the target machine.