CleanShot X CLI

Use the cleanshot command to trigger CleanShot X actions.

Basic usage

cleanshot <subcommand> [flags]

Subcommands

Query commands

• •latest - Print path of most recent screenshot

Capture commands

• •all-in-one - Launch all-in-one capture tool
• •capture-area - Area capture
• •capture-fullscreen - Fullscreen capture
• •capture-window - Window capture
• •capture-previous-area - Repeat last screenshot
• •self-timer - Self-timer capture
• •scrolling-capture - Scrolling capture

Recording

• •record-screen - Screen recording

OCR

• •capture-text - OCR text recognition

Utility

• •pin - Pin image file
• •open-annotate - Annotate image file
• •open-from-clipboard - Annotate clipboard image
• •toggle-desktop-icons - Toggle desktop icons visibility
• •hide-desktop-icons - Hide desktop icons
• •show-desktop-icons - Show desktop icons
• •add-quick-access-overlay - Add quick access overlay
• •open-history - Open capture history
• •restore-recently-closed - Restore recently deleted
• •open-settings - Open settings

Flags

Coordinate parameters

• •-x <int> - X coordinate (origin at lower left)
• •-y <int> - Y coordinate
• •-width <int> - Width in pixels
• •-height <int> - Height in pixels
• •-display <int> - Display number (1=main, 2=secondary, etc.)

Action parameters

• •-action <string> - Post-capture action: copy, save, annotate, upload, pin
• •-filepath <path> - File path for pin/annotate/OCR
• •-tab <string> - Settings tab: general, wallpaper, shortcuts, quickaccess, recording, screenshots, annotate, cloud, advanced, about
• •-path <dir> - Screenshot directory (default: ~/Downloads/screens)

Boolean flags

• •-start - Auto-start scrolling capture
• •-autoscroll - Enable automatic scrolling
• •-linebreaks - Preserve line breaks in OCR text

Examples

# Get latest screenshot
cleanshot latest
cleanshot latest -path ~/Pictures/screenshots

# Simple captures
cleanshot capture-area
cleanshot capture-fullscreen

# With coordinates
cleanshot capture-area -x 100 -y 120 -width 200 -height 150

# Save and print path
cleanshot capture-area -action save
cleanshot capture-fullscreen -action save -path ~/Pictures/screenshots

# Scrolling capture
cleanshot scrolling-capture -start -autoscroll

# Screen recording with region
cleanshot record-screen -x 0 -y 0 -width 1920 -height 1080 -display 1

# OCR
cleanshot capture-text -linebreaks
cleanshot capture-text -filepath ~/screenshot.png

# Annotate
cleanshot open-annotate -filepath ~/screenshot.png
cleanshot open-from-clipboard

# Settings
cleanshot open-settings -tab shortcuts

# Help
cleanshot help

Key features

• •Automatically detects and prints screenshot path when using -action save
• •Default screenshot directory: ~/Downloads/screens
• •Boolean flags don't require values
• •Waits up to 10 seconds for screenshot to appear

Usage examples

When user requests:

• •"what's my latest screenshot" → cleanshot latest
• •"get the most recent screenshot path" → cleanshot latest
• •"take a screenshot" → cleanshot capture-area or cleanshot capture-fullscreen
• •"save a screenshot" → cleanshot capture-area -action save
• •"record my screen" → cleanshot record-screen
• •"extract text from image" → cleanshot capture-text -filepath <path>
• •"annotate this image" → cleanshot open-annotate -filepath <path>
• •"hide desktop icons" → cleanshot hide-desktop-icons
• •"scrolling screenshot" → cleanshot scrolling-capture
• •"capture this specific region" → use coordinate parameters

Always confirm which capture type the user wants if ambiguous.