Screenshot command

Capture images of application windows for documentation and testing

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

Auto-generated

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

Relative path

Relative paths are resolved from current directory:

agent-native screenshot Safari screenshots/test.png

Creates: ./screenshots/test.png

Absolute path

Absolute paths are used as-is:

agent-native screenshot Safari /Users/me/Desktop/capture.png

Creates: /Users/me/Desktop/capture.png

Tilde expansion

Home directory shortcut is expanded:

agent-native screenshot Safari ~/Pictures/app.png

Creates: /Users/username/Pictures/app.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.

Related commands

• 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