Skip to main content

​
Overview

agent-desktop uses three exit codes to indicate the outcome of a command. These codes enable precise error handling in scripts and automation workflows. 
agent-desktop snapshot -i
echo $?  # Check exit code

​
Exit Code Reference

​
0
success
Success - Command completed successfullyThe command executed without errors. JSON output on stdout contains "ok": true.
agent-desktop snapshot --app Finder -i
# Exit code: 0

{
  "version": "1.0",
  "ok": true,
  "command": "snapshot",
  "data": { ... }
}
​
1
error
Structured Error - Command failed with a known error conditionThe command encountered a runtime error (permission denied, element not found, timeout, etc.). JSON output on stdout contains "ok": false with error details.
agent-desktop click @e99
# Exit code: 1 (element doesn't exist)

{
  "version": "1.0",
  "ok": false,
  "command": "click",
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "No element matched @e99",
    "suggestion": "Run 'snapshot' to refresh refs"
  }
}
​
2
error
Argument Parse Error - Invalid command-line argumentsThe command syntax was incorrect or required arguments were missing. Error message printed to stderr (not JSON).
agent-desktop snapshot --invalid-flag
# Exit code: 2
# Error: unexpected argument '--invalid-flag'

​
Error Codes (Exit Code 1)

When exit code is 1, the JSON output includes a machine-readable error code:
CodeMeaningRecovery
PERM_DENIEDAccessibility permission not grantedGrant permission in System Settings
ELEMENT_NOT_FOUNDNo element matched the ref or queryRun snapshot to get updated refs
APP_NOT_FOUNDApplication not running or no windowsLaunch the app first
STALE_REFRef is from a previous snapshotRun snapshot to refresh refs
ACTION_FAILEDThe OS rejected the actionVerify element supports the action
TIMEOUTWait condition expiredIncrease timeout or check condition
INVALID_ARGSInvalid argument valuesCheck argument format
ACTION_NOT_SUPPORTEDAction not available for this elementUse a different action
WINDOW_NOT_FOUNDWindow not foundVerify window exists with list-windows
PLATFORM_NOT_SUPPORTEDFeature not available on this OSCheck platform support
INTERNALUnexpected internal errorReport as bug

​
Scripting Examples

​
Bash: Handle Errors

#!/bin/bash

if agent-desktop snapshot --app Safari -i > /tmp/snapshot.json; then
  echo "Snapshot successful"
else
  exit_code=$?
  if [ $exit_code -eq 1 ]; then
    echo "Runtime error - check JSON output"
    cat /tmp/snapshot.json
  elif [ $exit_code -eq 2 ]; then
    echo "Invalid arguments"
  fi
  exit $exit_code
fi

​
Python: Parse JSON Errors

import subprocess
import json
import sys

result = subprocess.run(
    ["agent-desktop", "click", "@e3"],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    data = json.loads(result.stdout)
    print(f"Success: {data['command']}")
elif result.returncode == 1:
    error = json.loads(result.stdout)
    print(f"Error {error['error']['code']}: {error['error']['message']}")
    if error['error'].get('suggestion'):
        print(f"Suggestion: {error['error']['suggestion']}")
    sys.exit(1)
else:
    print(f"Argument error: {result.stderr}", file=sys.stderr)
    sys.exit(2)

​
Node.js: Retry on Stale Ref

const { execSync } = require('child_process');

function runCommand(cmd) {
  try {
    const output = execSync(cmd, { encoding: 'utf8' });
    return JSON.parse(output);
  } catch (error) {
    if (error.status === 1) {
      const result = JSON.parse(error.stdout);
      if (result.error.code === 'STALE_REF') {
        console.log('Stale ref detected, refreshing snapshot...');
        runCommand('agent-desktop snapshot -i');
        return runCommand(cmd); // Retry
      }
      throw new Error(`${result.error.code}: ${result.error.message}`);
    } else if (error.status === 2) {
      throw new Error(`Invalid arguments: ${error.stderr}`);
    }
  }
}

runCommand('agent-desktop click @e5');

​
Best Practices

Always check exit codes in scripts to handle errors gracefully
Parse JSON on exit code 1 to get structured error information
Use error codes for conditional logic rather than parsing error messages
Exit code 2 errors write to stderr, not stdout, and are not JSON formatted

Build docs developers (and LLMs) love

Get started for freeTalk to us