CLI

Common Commands

These cover the usual capture, OCR, clipboard, and window workflows.

readshot list-displays
readshot list-displays --json
readshot list-windows
readshot list-windows --json
readshot capture --interactive --output capture.png
readshot capture --interactive --output capture.png --json
readshot capture-text --interactive --json
readshot capture-and-ocr --interactive --also-image capture.png --json
readshot ocr --input capture.png --json
readshot mcp-config
readshot completions zsh

Commands

Interactive Capture

--interactive opens the same Readshot region selector used by the app. Drag a region and release to capture immediately. Press Enter for the full display or Esc to cancel.

readshot capture --interactive --output capture.png
readshot capture-text --interactive
readshot capture-and-ocr --interactive

Interactive capture can be combined with clipboard output, format selection, delay timers, and cursor controls where those options apply.

Targets

Display captures default to the primary display. Use list-displays to find display ids and --rect x,y,width,height to capture a region.

readshot list-displays --json
readshot capture --display 1 --rect 100,100,800,600 --output region.png

Window captures use ids from list-windows. Window rectangles are relative to the window's top-left corner.

readshot list-windows
readshot capture-window --window 11474 --output window.png
readshot capture-window --window 11474 --rect 40,40,900,600 --output panel.png

Image Output

capture and capture-window write PNG by default. Use --format for other image formats.

readshot capture --format png --output capture.png
readshot capture --format jpg --output capture.jpg
readshot capture --format tiff --output capture.tiff
readshot capture --format webp --output capture.webp
readshot capture --interactive --clipboard

Use --output - to write image bytes to stdout. This is the default when neither --output nor --clipboard is supplied.

Use --json to print capture metadata after saving or copying the image. Image capture commands require --output PATH or --clipboard when JSON is enabled.

readshot capture --interactive --output capture.png --json
readshot capture-window --window 11474 --output window.png --json
readshot capture --interactive --clipboard --json

Text Output

capture-text captures a region, runs OCR, and writes recognized text. ocr runs OCR on an existing image. OCR uses automatic language detection by default.

readshot capture-text --interactive
readshot capture-text --rect 100,100,800,600 --clipboard
readshot ocr --input capture.png --output text.txt
readshot ocr --input capture.png --clipboard

Use --input - with ocr to read image bytes from stdin. --languages accepts comma-separated BCP-47 hints; omit it for automatic detection.

cat capture.png | readshot ocr --input -
readshot ocr --input capture.png --languages en-US,fr-FR

Use --json to include OCR metadata such as confidence, image size, language hints, and positioned OCR lines when the platform engine returns them.

readshot capture-text --interactive --json
readshot ocr --input capture.png --json

Combined Image and OCR

capture-and-ocr writes OCR text and can save the captured image at the same time.

readshot capture-and-ocr --interactive --also-image capture.png --output text.txt
readshot capture-and-ocr --rect 100,100,800,600 --also-image capture.png
readshot capture-and-ocr --interactive --also-image capture.png --json

MCP Config

mcp-config prints a standard mcpServers JSON snippet for MCP stdio hosts. Use the short command when the host inherits your shell PATH, or pass the absolute app-bundle path for desktop apps.

readshot mcp-config
readshot mcp-config --command /Applications/Readshot.app/Contents/MacOS/readshot-mcp

JSON Output

--json returns stable metadata for scripts. Capture JSON includes kind, image size, source, output path, and clipboard state. OCR JSON includes text, confidence, image size, language hints, and positioned lines when the platform engine returns them.

readshot capture --output capture.png --json
readshot capture-text --json
readshot ocr --input capture.png --json

Shell Completions

Generate zsh, bash, fish, PowerShell, or Elvish completions from the same command tree used by readshot --help.

readshot completions zsh > _readshot
readshot completions bash > readshot.bash
readshot completions fish > readshot.fish

Timing, Cursor, and Window Options

Use --delay SECONDS for menus, popovers, hover states, or other transient UI. The cursor is hidden by default; use --show-cursor when documenting pointer state.

readshot capture --delay 2 --interactive --output menu.png
readshot capture --interactive --show-cursor --output pointer.png
readshot capture-window --window 11474 --window-shadow --output window.png
readshot capture-window --window 11474 --no-window-shadow --output tight.png

Use readshot --help or readshot <command> --help for the complete option list.

Output Destinations