Skip to main content
The screenshot command captures images of application windows.

​
Overview

agent-native screenshot <app> [path] [options]

​
Arguments

​
app
string
required
Application name or bundle identifier
​
path
string
Output file path (defaults to auto-generated temp file)

​
Options

​
--json
boolean
Output as JSON with path and dimensions

​
Examples

​
Basic screenshot

agent-native screenshot Safari
Output: 
/var/folders/xy/abc123/T/agent-native-F8E2B1C4-5D6A-7890-B1C2-D3E4F5A6B7C8.png

​
Specify output path

agent-native screenshot Safari ~/Desktop/safari-window.png
Output: 
/Users/username/Desktop/safari-window.png

​
JSON output

agent-native screenshot Terminal --json
Output: 
{
  "path": "/var/folders/xy/abc123/T/agent-native-12345678.png",
  "width": 1920,
  "height": 1080
}

​
Capture with tilde expansion

agent-native screenshot Slack ~/Documents/screenshots/slack-$(date +%Y%m%d).png

​
Behavior

​
Window selection

The command captures the frontmost window of the specified application.
If an app has multiple windows, only the active/front window is captured.

​
Image format

Screenshots are always saved as PNG files with the following characteristics:
  • Format: PNG (Portable Network Graphics)
  • Resolution: Native display resolution (Retina/HiDPI aware)
  • Quality: Lossless compression
  • Transparency: Preserved if window has transparent areas

​
File path handling

When no path is specified:
agent-native screenshot Safari
Files are created in the system temp directory with unique names:
/var/folders/xy/abc123/T/agent-native-UUID.png

​
Overwriting files

If the output file already exists, it will be overwritten without warning.
# First screenshot
agent-native screenshot Safari ~/capture.png

# This overwrites the previous file
agent-native screenshot Safari ~/capture.png

​
Use cases

​
Visual testing

#!/bin/bash

# Baseline screenshot
agent-native screenshot MyApp ~/test/baseline.png

# Perform actions
agent-native click @n10
agent-native fill @n5 "test data"

# Capture result
agent-native screenshot MyApp ~/test/result.png

# Compare (using external tool)
compare ~/test/baseline.png ~/test/result.png ~/test/diff.png

​
Documentation generation

#!/bin/bash

# Setup app state
agent-native click Safari --role Button --title "Preferences"
agent-native wait Safari --role Window --title "Preferences"

# Capture for documentation
agent-native screenshot Safari ~/docs/images/preferences-window.png

# Annotate (using external tool)
annotate ~/docs/images/preferences-window.png

​
Bug reports

#!/bin/bash

BUG_DIR="~/bugs/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUG_DIR"

# Reproduce issue
agent-native click @n5
agent-native fill @n10 "problematic input"
agent-native click @n15

# Capture error state
agent-native screenshot MyApp "$BUG_DIR/error-state.png"

# Get error message
agent-native get text MyApp --role StaticText --label "Error" > "$BUG_DIR/error.txt"

echo "Bug report saved to $BUG_DIR"

​
Progress monitoring

#!/bin/bash

OUTPUT_DIR="~/monitoring/$(date +%Y%m%d)"
mkdir -p "$OUTPUT_DIR"

for i in {1..10}; do
  echo "Capture $i/10"
  
  # Perform action
  agent-native click @n8
  
  # Wait for change
  sleep 2
  
  # Capture state
  TIMESTAMP=$(date +%H%M%S)
  agent-native screenshot MyApp "$OUTPUT_DIR/state-$TIMESTAMP.png"
done

echo "Captured 10 screenshots in $OUTPUT_DIR"

​
Automated tutorials

#!/bin/bash

TUTORIAL_DIR="~/tutorial-screenshots"
mkdir -p "$TUTORIAL_DIR"

STEP=1

# Step 1: Initial state
agent-native screenshot MyApp "$TUTORIAL_DIR/step-$STEP.png"
STEP=$((STEP+1))

# Step 2: Click New
agent-native click @n5
sleep 0.5
agent-native screenshot MyApp "$TUTORIAL_DIR/step-$STEP.png"
STEP=$((STEP+1))

# Step 3: Fill form
agent-native fill @n10 "Example Name"
sleep 0.3
agent-native screenshot MyApp "$TUTORIAL_DIR/step-$STEP.png"
STEP=$((STEP+1))

# Step 4: Submit
agent-native click @n12
agent-native wait MyApp --role StaticText --title "Success"
agent-native screenshot MyApp "$TUTORIAL_DIR/step-$STEP.png"

echo "Tutorial screenshots saved to $TUTORIAL_DIR"

​
Regression testing

#!/bin/bash

BASELINE_DIR="~/test/baseline"
CURRENT_DIR="~/test/current/$(date +%Y%m%d)"
DIFF_DIR="~/test/diff/$(date +%Y%m%d)"

mkdir -p "$CURRENT_DIR" "$DIFF_DIR"

# Test scenarios
SCENARIOS=("home" "settings" "profile" "search")

for scenario in "${SCENARIOS[@]}"; do
  echo "Testing scenario: $scenario"
  
  # Navigate to scenario
  # ... (scenario-specific navigation)
  
  # Capture current state
  agent-native screenshot MyApp "$CURRENT_DIR/$scenario.png"
  
  # Compare with baseline
  if [ -f "$BASELINE_DIR/$scenario.png" ]; then
    if ! compare -metric RMSE \
      "$BASELINE_DIR/$scenario.png" \
      "$CURRENT_DIR/$scenario.png" \
      "$DIFF_DIR/$scenario.png" 2>&1 | grep -q "^0"; then
      echo "  FAIL: Visual regression detected in $scenario"
    else
      echo "  PASS: $scenario matches baseline"
    fi
  else
    echo "  SKIP: No baseline for $scenario"
  fi
done

​
Advanced patterns

​
Screenshot on error

#!/bin/bash

trap 'agent-native screenshot MyApp ~/error-$(date +%s).png' ERR

set -e  # Exit on error

# Your automation
agent-native click @n5
agent-native fill @n10 "data"
agent-native click @n15

# If any command fails, screenshot is automatically captured

​
Timestamped series

#!/bin/bash

SESSION=$(date +%Y%m%d-%H%M%S)
DIR="~/screenshots/$SESSION"
mkdir -p "$DIR"

function capture() {
  local name=$1
  local timestamp=$(date +%s%3N)  # milliseconds
  agent-native screenshot MyApp "$DIR/${timestamp}-${name}.png"
  echo "Captured: $name"
}

# Capture throughout workflow
capture "initial"
agent-native click @n5
capture "after-click"
agent-native fill @n10 "test"
capture "after-fill"
agent-native click @n15
capture "final"

echo "Session screenshots saved to $DIR"

​
Conditional screenshots

#!/bin/bash

if [ "$(agent-native is enabled @n10)" = "false" ]; then
  echo "Button is disabled, capturing state"
  agent-native screenshot MyApp ~/debug/disabled-button.png
  exit 1
fi

agent-native click @n10

# Verify success
if agent-native wait MyApp --role Alert --timeout 2 2>/dev/null; then
  echo "Alert appeared, capturing"
  agent-native screenshot MyApp ~/debug/alert-state.png
fi

​
Integration with other tools

​
Image processing (ImageMagick)

# Capture and resize
SCREENSHOT=$(agent-native screenshot Safari)
convert "$SCREENSHOT" -resize 800x600 ~/output.png

# Capture and annotate
SCREENSHOT=$(agent-native screenshot Safari)
convert "$SCREENSHOT" -pointsize 36 -fill red -annotate +50+50 'ERROR' ~/annotated.png

# Capture and crop
SCREENSHOT=$(agent-native screenshot Safari)
convert "$SCREENSHOT" -crop 800x600+100+50 ~/cropped.png

​
Comparison tools

# Using compare (ImageMagick)
agent-native screenshot MyApp ~/before.png
# ... perform actions ...
agent-native screenshot MyApp ~/after.png
compare ~/before.png ~/after.png ~/diff.png

# Using pixelmatch
agent-native screenshot MyApp ~/img1.png
# ... perform actions ...
agent-native screenshot MyApp ~/img2.png
pixelmatch ~/img1.png ~/img2.png ~/diff.png 0.1

​
Upload to services

# Capture and upload
SCREENSHOT=$(agent-native screenshot Safari)
curl -F "file=@$SCREENSHOT" https://api.example.com/upload

# Capture and share
SCREENSHOT=$(agent-native screenshot Slack)
cp "$SCREENSHOT" ~/Dropbox/Public/
echo "https://dl.dropboxusercontent.com/u/123/$(basename $SCREENSHOT)"

​
Tips

For consistent screenshots, ensure the application window is fully visible and not obscured by other windows.
Add small delays (100-500ms) before screenshots to ensure UI has fully updated after actions.
Use descriptive filenames with timestamps for easier organization and debugging.
Screenshots capture only the frontmost window. If you need multiple windows, activate each one before capturing.
The command requires the app to have at least one window. Headless or background apps without windows will fail.
  • wait - Wait for UI state before capturing
  • snapshot - Get element structure before screenshot
  • get title - Verify window title before capture
  • click - Navigate to desired state

Build docs developers (and LLMs) love

Get started for freeTalk to us