DownloadURL scheme API
Our macOS app exposes actions that let 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:
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:
✨ All-In-One mode
/all-in-one
Launch the "All-In-One" mode. You can also provide the optional parameters to open the tool at specific location. Point (0,0) is located in the lower left corner of the screen.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| 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:
Requires CleanShot 4.2 or later. Parameters x, y, width, height, display require version 4.7 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:
| Parameter | Required | Description |
|---|---|---|
| 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. |
| action | (optional) | Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin). |
Example:
Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.
/capture-previous-area
Repeats last taken screenshot.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| action | (optional) | Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) |
Example:
Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.
/capture-fullscreen
Takes a fullscreen screenshot.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| action | (optional) | Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) |
Example:
Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.
/capture-window
Opens "Capture Window" mode.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| action | (optional) | Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) |
Example:
Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.
/self-timer
Opens "Capture Area" mode with self-timer.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| action | (optional) | Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) |
Example:
Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.
/scrolling-capture
Opens "Scrolling Capture" mode. You can also provide the optional parameters to open the tool at specific location. Point (0,0) is located in the lower left corner of the screen.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| 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. |
| start | (optional) | Automatically start capture (true/false) |
| autoscroll | (optional) | Enable auto-scroll mode (true/false) |
Example:
Requires CleanShot 3.5.1 or later. Parameters start and autoscroll require version 4.7 or later.
/pin
Opens the specified file as a pinned screenshot.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| 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:
Requires CleanShot 3.5.1 or later.
🎥 Screen Recording
/record-screen
Opens "Record Screen" mode. You can also provide the optional parameters to open the tool at specific location. Point (0,0) is located in the lower left corner of the screen.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| 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:
or
Requires CleanShot 3.5.1 or later. Parameters x, y, width, height, display require version 4.7 or later.
📖 Text Recognition
/capture-text
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:
| Parameter | Required | Description |
|---|---|---|
| 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:
Requires CleanShot 3.8.1 and macOS 10.15 or later.
✏️ Annotate
/open-annotate
Opens specified file in Annotate.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| 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:
Requires CleanShot 3.8.1 or later.
/open-from-clipboard
Opens the image from clipboard in Annotate.
Example:
Requires CleanShot 3.5.1 or later.
🖥 Desktop icons
/toggle-desktop-icons
Toggles Desktop icons visibility.
Example:
Requires CleanShot 3.5.1 or later.
/hide-desktop-icons
Hides Desktop icons.
Example:
Requires CleanShot 3.8.1 or later.
/show-desktop-icons
Shows Desktop icons.
Example:
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:
| Parameter | Required | Description |
|---|---|---|
| filepath | (required) | path to the image or video (PNG/JPEG/MP4) you want to open. |
Example:
Requires CleanShot 3.8.1 or later.
⏳ History management
/open-history
Opens capture history.
Example:
Requires CleanShot 4.4 or later.
/restore-recently-closed
Restores the most recently closed file from history.
Example:
Requires CleanShot 3.5.1 or later.
⚙️ Settings
/open-settings
Opens CleanShot settings. You can also specify the tab to open.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| tab | (optional) | Specify the tab to open. Possible values: general, wallpaper, shortcuts, quickaccess, recording, screenshots, annotate, cloud, advanced, about |
Example:
Requires CleanShot 4.7 or later.
'%3e%3cpath%20fill='%23fff'%20fill-rule='evenodd'%20d='M19.582%205.162a2.51%202.51%200%200%200-1.74-1.744C16.282%203%2010.01%203%2010.01%203s-6.258-.008-7.833.418a2.51%202.51%200%200%200-1.74%201.744A26%2026%200%200%200%200%2010.009c-.005%201.62.141%203.236.436%204.828a2.51%202.51%200%200%200%201.74%201.744C3.733%2017%2010.01%2017%2010.01%2017s6.257%200%207.833-.42a2.51%202.51%200%200%200%201.74-1.743A26%2026%200%200%200%2020%2010.009a26%2026%200%200%200-.418-4.847M8.007%2013.007V7.001l5.221%203.008z'%20clip-rule='evenodd'/%3e%3c/g%3e%3cdefs%3e%3cclipPath%20id='a'%3e%3cpath%20fill='%23fff'%20d='M0%200h20v20H0z'/%3e%3c/clipPath%3e%3c/defs%3e%3c/svg%3e)
