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

✨ All-In-One mode

/all-in-one

Launch the "All-In-One" mode.

Example:

cleanshot://all-in-one

Requires CleanShot 4.2 or later.

📸 Screenshots

/capture-area

Opens the standard "Capture Area" mode. You can also provide the optional parameters and capture the screen instantly. Point (0,0) is located in the lower left corner of the screen.

Parameters:

x (optional)
y (optional)
width (optional)
height (optional)
display (optional) - Capture a specified display: 1 is the main display, 2 is the secondary, etc. If not specified, CleanShot will use the display which the cursor is on

Example:

cleanshot://capture-area

cleanshot://capture-area?x=100&y=120&width=200&height=150&display=1

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

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.

Opens Text Recognition (OCR) tool or extracts text from the specified file. You can also provide the optional parameters (x, y, width, height, display) and capture the text from a specified area on screen. Point (0,0) is located in the lower left corner of the screen.

Parameters:

filepath (optional) - path to the image file (PNG/JPEG) that contains the text you want to extract.
x (optional)
y (optional)
width (optional)
height (optional)
display (optional) - Capture a specified display: 1 is the main display, 2 is the secondary, etc. If not specified, CleanShot will use the display which the cursor is on
linebreaks (optional) - Keep (true) or remove (false) line breaks from copied text

Example:

cleanshot://capture-text

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

cleanshot://capture-text?x=100&y=120&width=200&height=150&display=1

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

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

Requires CleanShot 3.8.1 or later.