Skip to main content
Read the current plain-text content from the macOS system clipboard (pasteboard).

​
Usage

agent-desktop clipboard-get

​
Parameters

This command takes no parameters.

​
Response

​
text
string
required
The plain-text content currently in the clipboard. Returns an empty string if the clipboard is empty or contains only non-text data.

​
Examples

​
Read Clipboard Content

agent-desktop clipboard-get

{
  "version": "1.0",
  "ok": true,
  "command": "clipboard-get",
  "data": {
    "text": "Hello, world!"
  }
}

​
Empty Clipboard

agent-desktop clipboard-get

{
  "version": "1.0",
  "ok": true,
  "command": "clipboard-get",
  "data": {
    "text": ""
  }
}

​
Use Cases

Read content a user has copied:
# User copies text manually (cmd+c)
TEXT=$(agent-desktop clipboard-get | jq -r '.data.text')
echo "User copied: $TEXT"
Use native copy actions to extract data:
# Select text in an app
agent-desktop click @e3
agent-desktop press cmd+a
agent-desktop press cmd+c

# Read the copied text
agent-desktop clipboard-get
Transfer data between applications via clipboard:
# Copy from source app
agent-desktop click @e5
agent-desktop press cmd+c

# Read clipboard
DATA=$(agent-desktop clipboard-get | jq -r '.data.text')

# Paste to destination app
agent-desktop focus-window --app TextEdit
agent-desktop clipboard-set "$DATA"
agent-desktop press cmd+v
Monitor clipboard for changes:
# Store initial clipboard state
PREV=$(agent-desktop clipboard-get | jq -r '.data.text')

while true; do
  sleep 1
  CURR=$(agent-desktop clipboard-get | jq -r '.data.text')
  if [ "$CURR" != "$PREV" ]; then
    echo "Clipboard changed: $CURR"
    PREV="$CURR"
  fi
done

​
Clipboard Data Types

This command only reads plain text from the clipboard. Other data types are not supported:
  • Images: Not returned (use screenshot commands instead)
  • Files: Not returned (file paths may be returned as text if copied as text)
  • Rich text: Formatting is stripped; only plain text is returned
  • HTML: HTML source may be returned if copied as plain text
If the clipboard contains only non-text data (e.g., an image), the text field will be an empty string.

​
Permissions

Reading the clipboard requires macOS accessibility permission. If permission is not granted, the command will return a PERM_DENIED error: 
{
  "version": "1.0",
  "ok": false,
  "command": "clipboard-get",
  "error": {
    "code": "PERM_DENIED",
    "message": "Accessibility permission not granted",
    "suggestion": "Open System Settings > Privacy & Security > Accessibility and add your terminal app"
  }
}

​
Notes

  • The clipboard is a system-wide resource; reading it does not modify its contents
  • Newlines and special characters are preserved in the returned text
  • The clipboard content is read synchronously; there is no polling or waiting
  • If multiple clipboard items exist (macOS supports clipboard history in some apps), only the most recent item is returned

Build docs developers (and LLMs) love

Get started for freeTalk to us