Menu

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. 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:

  • 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://all-in-one

or

cleanshot://all-in-one?x=100&y=120&width=200&height=150&display=1

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:

  • 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:

cleanshot://capture-area

or

cleanshot://capture-area?action=annotate

or

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

Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.

/capture-previous-area

Repeats last taken screenshot.

Parameters:

  • action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin)

Example:

cleanshot://capture-previous-area

Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.

/capture-fullscreen

Takes a fullscreen screenshot.

Parameters:

  • action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin)

Example:

cleanshot://capture-fullscreen

Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later.

/capture-window

Opens "Capture Window" mode.

Parameters:

  • action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin)

Example:

cleanshot://capture-window

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:

  • action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin)

Example:

cleanshot://self-timer

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:

  • 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:

cleanshot://scrolling-capture

or

cleanshot://scrolling-capture?x=100&y=120&width=200&height=150&start=true&autoscroll=true

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:

  • 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. 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:

  • 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://record-screen

or

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

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:

  • 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

or

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

or

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

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 visibility.

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.

⏳  History management

/open-history

Opens capture history.

Example:

cleanshot://open-history

Requires CleanShot 4.4 or later.

/restore-recently-closed

Restores the most recently closed file from history.

Example:

cleanshot://restore-recently-closed

Requires CleanShot 3.5.1 or later.

⚙️  Settings

/open-settings

Opens CleanShot settings. You can also specify the tab to open.

Parameters:

  • tab (optional) - Specify the tab to open. Possible values: general, wallpaper, shortcuts, quickaccess, recording, screenshots, annotate, cloud, advanced, about

Example:

cleanshot://open-settings

or

cleanshot://open-settings?tab=recording

Requires CleanShot 4.7 or later.