> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt
> Use this file to discover all available pages before exploring further.

# Screenshot command

> Capture images of application windows for documentation and testing

The `screenshot` command captures images of application windows.

## Overview

```bash theme={null}
agent-native screenshot <app> [path] [options]
```

### Arguments

<ParamField path="app" type="string" required>
  Application name or bundle identifier
</ParamField>

<ParamField path="path" type="string">
  Output file path (defaults to auto-generated temp file)
</ParamField>

### Options

<ParamField query="--json" type="boolean">
  Output as JSON with path and dimensions
</ParamField>

## Examples

### Basic screenshot

```bash theme={null}
agent-native screenshot Safari
```

Output:

```bash theme={null}
/var/folders/xy/abc123/T/agent-native-F8E2B1C4-5D6A-7890-B1C2-D3E4F5A6B7C8.png
```

### Specify output path

```bash theme={null}
agent-native screenshot Safari ~/Desktop/safari-window.png
```

Output:

```bash theme={null}
/Users/username/Desktop/safari-window.png
```

### JSON output

```bash theme={null}
agent-native screenshot Terminal --json
```

Output:

```json theme={null}
{
  "path": "/var/folders/xy/abc123/T/agent-native-12345678.png",
  "width": 1920,
  "height": 1080
}
```

### Capture with tilde expansion

```bash theme={null}
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.

<Info>
  If an app has multiple windows, only the active/front window is captured.
</Info>

### 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

<Tabs>
  <Tab title="Auto-generated">
    When no path is specified:

    ```bash theme={null}
    agent-native screenshot Safari
    ```

    Files are created in the system temp directory with unique names:

    ```
    /var/folders/xy/abc123/T/agent-native-UUID.png
    ```
  </Tab>

  <Tab title="Relative path">
    Relative paths are resolved from current directory:

    ```bash theme={null}
    agent-native screenshot Safari screenshots/test.png
    ```

    Creates: `./screenshots/test.png`
  </Tab>

  <Tab title="Absolute path">
    Absolute paths are used as-is:

    ```bash theme={null}
    agent-native screenshot Safari /Users/me/Desktop/capture.png
    ```

    Creates: `/Users/me/Desktop/capture.png`
  </Tab>

  <Tab title="Tilde expansion">
    Home directory shortcut is expanded:

    ```bash theme={null}
    agent-native screenshot Safari ~/Pictures/app.png
    ```

    Creates: `/Users/username/Pictures/app.png`
  </Tab>
</Tabs>

### Overwriting files

<Warning>
  If the output file already exists, it will be overwritten without warning.
</Warning>

```bash theme={null}
# First screenshot
agent-native screenshot Safari ~/capture.png

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

## Use cases

### Visual testing

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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)

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<Tip>
  For consistent screenshots, ensure the application window is fully visible and not obscured by other windows.
</Tip>

<Tip>
  Add small delays (100-500ms) before screenshots to ensure UI has fully updated after actions.
</Tip>

<Tip>
  Use descriptive filenames with timestamps for easier organization and debugging.
</Tip>

<Warning>
  Screenshots capture only the frontmost window. If you need multiple windows, activate each one before capturing.
</Warning>

<Info>
  The command requires the app to have at least one window. Headless or background apps without windows will fail.
</Info>

## Related commands

* [`wait`](/commands/wait) - Wait for UI state before capturing
* [`snapshot`](/commands/snapshot) - Get element structure before screenshot
* [`get title`](/commands/state#get-title) - Verify window title before capture
* [`click`](/commands/interaction#click) - Navigate to desired state