URL scheme API

Our macOS app exposes actions that lets pro users and developers of other apps send commands to CleanShot. This page explains how it works.

Overview

URL scheme is a special type of link that works just like a normal https:// link you use every day. Instead of opening a webpage, it performs a specific action in the CleanShot macOS app.

Commands are sent to CleanShot by constructing a special URL:

cleanshot://command-name?parameter1=value1&parameter2=value2

Opening these links will launch the app and execute the command. For example, here's how you would tell CleanShot to take a fullscreen screenshot:

cleanshot://capture-fullscreen

📸  Screenshots

/capture-area

Opens the standard "Capture Area" mode.

Example:

cleanshot://capture-area

Requires CleanShot 3.5.1 or later.

/capture-previous-area

Repeats last taken screenshot.

Example:

cleanshot://capture-previous-area

Requires CleanShot 3.5.1 or later.

/capture-fullscreen

Takes a fullscreen screenshot.

Example:

cleanshot://capture-fullscreen

Requires CleanShot 3.5.1 or later.

/capture-window

Opens "Capture Window" mode.

Example:

cleanshot://capture-window

Requires CleanShot 3.5.1 or later.

/self-timer

Opens "Capture Area" mode with self-timer.

Example:

cleanshot://self-timer

Requires CleanShot 3.5.1 or later.

/scrolling-capture

Opens "Scrolling Capture" mode.

Example:

cleanshot://scrolling-capture

Requires CleanShot 3.5.1 or later.

/pin

Opens the specified file as a pinned screenshot.

Parameters:

  • filepath (optional) - path to the file (PNG/JPEG) you want to pin. If you don’t pass this parameter, CleanShot will ask to select the file manually.

Example:

cleanshot://pin

or

cleanshot://pin?filepath=/Users/john/Desktop/my%20screenshot.png

Requires CleanShot 3.5.1 or later.

🎥  Screen Recording

/record-screen

Opens "Record Screen" mode.

Example:

cleanshot://record-screen

Requires CleanShot 3.5.1 or later.

📖  Text Recognition

/capture-text

Opens Text Recognition (OCR) tool or extracts text from the specified file.

Parameters:

  • filepath (optional) - path to the image file (PNG/JPEG) that contains the text you want to extract.

Example:

cleanshot://capture-text

or

cleanshot://capture-text?filepath=/Users/john/Desktop/my%20screenshot.png

Requires CleanShot 3.8.1 and macOS 10.15 or later.

✏️  Annotate

/open-annotate

Opens specified file in Annotate.

Parameters:

  • filepath (optional) - path to the image (PNG/JPEG) you want to open. If you don’t pass this parameter, CleanShot will ask to select the file manually.

Example:

cleanshot://open-annotate

or

cleanshot://open-annotate?filepath=/Users/john/Desktop/my%20screenshot.png

Requires CleanShot 3.8.1 or later.

/open-from-clipboard

Opens the image from clipboard in Annotate.

Example:

cleanshot://open-from-clipboard

Requires CleanShot 3.5.1 or later.

🖥  Desktop icons

/toggle-desktop-icons

Toggles Desktop icons visiblity.

Example:

cleanshot://toggle-desktop-icons

Requires CleanShot 3.5.1 or later.

/hide-desktop-icons

Hides Desktop icons.

Example:

cleanshot://hide-desktop-icons

Requires CleanShot 3.8.1 or later.

/show-desktop-icons

Shows Desktop icons.

Example:

cleanshot://show-desktop-icons

Requires CleanShot 3.8.1 or later.

⚡️  Quick Access Overlay

/add-quick-access-overlay

Opens a new Quick Access Overlay with the specified image or video.

Parameters:

  • filepath (required) - path to the image or video (PNG/JPEG/MP4) you want to open.

Example:

cleanshot://add-quick-access-overlay?filepath=/Users/john/Desktop/my%20screenshot.png

Requires CleanShot 3.8.1 or later.

/restore-recently-closed

Restores recently closed Quick Access Overlay item.

Example:

cleanshot://restore-recently-closed

Requires CleanShot 3.5.1 or later.