Machine API Reference

The context.machine API is available to plugins that declare machineCapabilities in their manifest. It allows plugins to interact with the user's connected machine through PIE Connect.

context.machine.isOnline()

Check if the user has at least one online machine.

Returns: Promise<boolean>

const online = await context.machine.isOnline();

context.machine.list()

List all connected machines for the current user.

Returns: Promise<Array<{ machineId: string, capabilities: string[], connectedAt: number }>>

const machines = await context.machine.list();

context.machine.execute(capability, params)

Execute a command on the user's machine. The plugin's manifest must declare the capability, and the user must have approved it at install time.

Parameters:

• capability (string) — The capability to execute (e.g., "machine.info")
• params (object) — Parameters for the capability

Returns: Promise<any>

const result = await context.machine.execute('machine.info', {});

context.machine.upload(macPath)

Convenience method to upload a file from the Mac to PIE cloud storage. Equivalent to execute('file.transfer', { action: 'upload', path: macPath }).

Parameters:

• macPath (string) — File path on the Mac (supports ~ for home directory)

Returns: Promise<{ action, fileId, url, size, filename, mimeType, sourcePath }>

const uploaded = await context.machine.upload('~/Documents/report.pdf');
console.log(uploaded.fileId, uploaded.url); // file ID and view URL

context.machine.download(urlOrGcsPath, macSavePath)

Convenience method to download a file from the cloud to the Mac. Equivalent to execute('file.transfer', { action: 'download', ... }).

Parameters:

• urlOrGcsPath (string) — A URL to download from, or a GCS path from a previous upload
• macSavePath (string) — Path on the Mac to save the file

Returns: Promise<{ action, savedTo, size, filename }>

await context.machine.download('https://example.com/file.pdf', '~/Downloads/file.pdf');

---

Capabilities Reference

machine.info

Read basic machine information.

Risk: Low Platforms: macOS, Linux, Windows Parameters: None Returns:

{
  "hostname": "Jakes-MacBook-Pro",
  "platform": "darwin",
  "arch": "arm64",
  "osType": "Darwin",
  "osRelease": "24.0.0",
  "osVersion": "Darwin Kernel Version 24.0.0",
  "uptime": 123456,
  "totalMemory": 17179869184,
  "freeMemory": 8589934592,
  "cpus": 10,
  "nodeVersion": "v22.0.0",
  "homeDir": "/Users/jake",
  "username": "jake"
}

clipboard.read

Read the current clipboard contents.

Risk: Medium Platforms: macOS, Linux, Windows Parameters: None Returns:

{
  "content": "Hello, world!",
  "length": 13
}

clipboard.write

Write text to the system clipboard.

Risk: Medium Platforms: macOS, Linux, Windows Parameters:

Name	Type	Description
text	string	The text to write to the clipboard (required)

Returns:

{
  "written": true,
  "length": 13
}

notifications.send

Send a desktop notification.

Risk: Low Platforms: macOS, Linux, Windows Parameters:

Name	Type	Description
title	string	Notification title (default: "PIE")
message	string	Notification body (default: "Notification from PIE")

Returns:

{
  "sent": true,
  "title": "PIE",
  "message": "Hello from PIE!"
}

messages.read

Read iMessages from the Mac's Messages database. macOS only. Requires Full Disk Access permission.

Risk: High Parameters:

Name	Type	Description
limit	number	Max messages to return (1-100, default: 5)
contact	string	Filter by contact (partial match)
after	string	ISO date string — only messages after this date

Returns:

{
  "messages": [
    {
      "text": "Hey, are you free tonight?",
      "fromMe": false,
      "date": "2025-01-15 14:30:00",
      "sender": "+15551234567"
    }
  ],
  "count": 1
}

screenshot.capture

Capture a screenshot of the Mac screen.

Risk: High Platforms: macOS Parameters:

Name	Type	Description
quality	number	JPEG quality (1-100, default: 60)
maxWidth	number	Max image width in pixels (default: 1280)

Returns:

{
  "image": "data:image/jpeg;base64,...",
  "width": 1280,
  "height": 800
}

desktop.control

Control mouse and keyboard on the Mac. macOS only. Requires Accessibility permission.

Risk: Critical Parameters:

Name	Type	Description
action	string	Required. One of: click, double_click, right_click, move, drag, scroll, type, press_key, info, open_app
x, y	number	Coordinates for click/move/scroll actions
startX, startY, endX, endY	number	Coordinates for drag action
deltaY	number	Scroll amount for scroll action
text	string	Text for type action
key	string	Key name or combo for press_key (e.g., "return", "cmd+c")
modifiers	string[]	Optional modifiers for press_key (["cmd", "shift"])
name	string	App name for open_app action

Returns: Object with action, success, and action-specific fields.

shell.run

Execute shell commands on the machine.

Risk: Critical Platforms: macOS, Linux, Windows Parameters:

Name	Type	Description
command	string	The shell command to execute (required)
cwd	string	Working directory (default: user home)
timeout	number	Timeout in ms (default: 30000, max: 120000)

Returns:

{
  "exitCode": 0,
  "stdout": "hello world\n",
  "stderr": "",
  "command": "echo hello world",
  "cwd": "/Users/jake"
}

filesystem

Read, write, list, search, move, copy, and delete files.

Risk: High Platforms: macOS, Linux, Windows Parameters:

Name	Type	Description
action	string	Required. One of: read, write, list, search, move, copy, delete, stat

Action: read — Read a file's contents (max 5MB)

Name	Type	Description
path	string	File path (supports ~ for home dir)
encoding	string	Encoding (default: utf-8)

Action: write — Write or append to a file

Name	Type	Description
path	string	File path
content	string	Content to write
append	boolean	Append instead of overwrite (default: false)

Action: list — List directory contents

Name	Type	Description
path	string	Directory path
recursive	boolean	Recurse into subdirectories (default: false)
glob	string	Filter by name pattern
showHidden	boolean	Include hidden files (default: false)

Action: search — Search file contents

Name	Type	Description
path	string	Directory to search in
pattern	string	Search pattern
maxResults	number	Max results (default: 200)

Action: move — Move or rename a file

Name	Type	Description
source	string	Source path
destination	string	Destination path

Action: copy — Copy a file or directory

Name	Type	Description
source	string	Source path
destination	string	Destination path

Action: delete — Delete a file or directory

Name	Type	Description
path	string	Path to delete
recursive	boolean	Required for directories (default: false)

Action: stat — Get file metadata

Name	Type	Description
path	string	File or directory path

Returns (stat example):

{
  "action": "stat",
  "path": "/Users/jake",
  "exists": true,
  "type": "directory",
  "size": 1024,
  "sizeHuman": "1.0KB",
  "created": "2024-01-01T00:00:00.000Z",
  "modified": "2025-03-14T12:00:00.000Z",
  "permissions": "755"
}

apps.automate

Automate macOS applications via scoped AppleScript. The script is always executed inside a tell application block for the specified app. Timeout is 30 seconds.

Risk: High Platforms: macOS Parameters:

Name	Type	Description
app	string	Application name (e.g., "Spotify", "Finder", "Calendar")
script	string	AppleScript commands to run inside tell application block

Safety: Scripts cannot contain the following patterns (use shell.run or filesystem instead): do shell script, run script, system attribute, path to startup disk, do script, POSIX file, call method, store script, load script, scripting additions.

Returns:

{
  "app": "Spotify",
  "output": "Playing",
  "success": true,
  "dictionary": "Commands: play — Play the current track; pause — Pause playback; ...\nClasses: track [props: name, artist, album, duration, ...]"
}

The dictionary field contains a condensed summary of the app's AppleScript scripting dictionary (sdef), automatically fetched in parallel with script execution and cached. It lists available commands and classes with their properties. This is especially useful on errors — the dictionary shows what commands are actually available so the script can be corrected.

Examples:

// Play Spotify
await context.machine.execute('apps.automate', {
  app: 'Spotify',
  script: 'play'
});

// Get current track
await context.machine.execute('apps.automate', {
  app: 'Spotify',
  script: 'get name of current track'
});

// Set volume
await context.machine.execute('apps.automate', {
  app: 'Spotify',
  script: 'set sound volume to 50'
});

// Create a reminder
await context.machine.execute('apps.automate', {
  app: 'Reminders',
  script: 'make new reminder with properties {name:"Buy groceries", body:"Milk, eggs, bread"}'
});

// Open a URL in Safari
await context.machine.execute('apps.automate', {
  app: 'Safari',
  script: 'open location "https://example.com"'
});

browser.data

Read browser tabs, history, and bookmarks from Safari and Chrome.

Risk: High Platforms: macOS Parameters:

Name	Type	Description
action	string	Required. One of: tabs, history, bookmarks
browser	string	"safari" or "chrome" (default: "safari")
limit	number	Max results (default: 50, max: 500)

Returns (tabs example):

{
  "action": "tabs",
  "browser": "safari",
  "tabs": [
    { "title": "GitHub", "url": "https://github.com", "windowIndex": 0 },
    { "title": "Google", "url": "https://google.com", "windowIndex": 0 }
  ],
  "count": 2
}

Returns (history example):

{
  "action": "history",
  "browser": "safari",
  "history": [
    { "url": "https://github.com", "title": "GitHub", "visit_date": "2025-03-14 10:30:00" }
  ],
  "count": 1,
  "limit": 50
}

contacts.read

Read contacts from macOS Contacts.

Risk: High Platforms: macOS Parameters:

Name	Type	Description
search	string	Filter by name (partial match)
limit	number	Max contacts to return (default: 50, max: 500)
fields	string[]	Fields to include: name, email, phone, company, address, birthday, notes (default: ["name", "email", "phone"])

Returns:

{
  "contacts": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "name": "Jane Doe",
      "emails": [{ "label": "work", "value": "[email protected]" }],
      "phones": [{ "label": "mobile", "value": "+15551234567" }]
    }
  ],
  "count": 1,
  "total": 342,
  "search": null,
  "fields": ["name", "email", "phone"]
}

calendar.read

Read events from macOS Calendar.

Risk: High Platforms: macOS Parameters:

Name	Type	Description
from	string	Start date (ISO format, default: today)
to	string	End date (ISO format, default: 7 days from start)
calendar	string	Filter by calendar name
limit	number	Max events to return (default: 50, max: 500)

Returns:

{
  "events": [
    {
      "summary": "Team Standup",
      "calendar": "Work",
      "startDate": "2025-03-14T09:00:00.000Z",
      "endDate": "2025-03-14T09:30:00.000Z",
      "location": "Zoom",
      "description": null,
      "allDay": false
    }
  ],
  "count": 1,
  "calendarCount": 4,
  "from": "2025-03-14T00:00:00.000Z",
  "to": "2025-03-21T00:00:00.000Z"
}

system.control

Read and control system settings.

Risk: Medium Platforms: macOS Parameters:

Name	Type	Description
action	string	Required. One of: volume, set_volume, dark_mode, set_dark_mode, wifi_status, bluetooth_devices, battery, running_apps, disk_usage, network_info
level	number	Volume level (0-100) for set_volume
enabled	boolean	Dark mode state for set_dark_mode

Returns (volume example):

{
  "action": "volume",
  "outputVolume": 75,
  "inputVolume": 80,
  "outputMuted": false
}

Returns (battery example):

{
  "action": "battery",
  "percent": 87,
  "powerSource": "AC Power",
  "status": "charging"
}

Returns (running_apps example):

{
  "action": "running_apps",
  "apps": [
    { "name": "Spotify", "bundleId": "com.spotify.client", "pid": 1234 },
    { "name": "Safari", "bundleId": "com.apple.Safari", "pid": 5678 }
  ],
  "count": 15
}

Returns (network_info example):

{
  "action": "network_info",
  "interfaces": [
    { "name": "en0", "ipv4": "192.168.1.100" }
  ],
  "publicIp": "203.0.113.1"
}

file.transfer

Upload files from the Mac to PIE cloud storage, or download files from the cloud to the Mac. Supports files up to 100MB. Uploaded files appear in the user's PIE Files and are associated with the calling plugin.

Risk: High Platforms: macOS, Linux, Windows Parameters:

Name	Type	Description
action	string	Required. "upload" or "download"

Action: upload — Upload a file from Mac to cloud

Name	Type	Description
path	string	File path on the Mac (supports ~ for home dir)

Returns (upload):

{
  "action": "upload",
  "fileId": "be3df226-9f8a-4ebe-9400-7cc238023bf3",
  "url": "/api/files/be3df226-.../view",
  "size": 76292,
  "filename": "report.pdf",
  "mimeType": "application/pdf",
  "sourcePath": "/Users/jake/Documents/report.pdf"
}

Action: download — Download a file from cloud to Mac

Name	Type	Description
url	string	URL to download from
gcsPath	string	GCS path from a previous upload (alternative to url)
savePath	string	Path on Mac to save the file (required)

Returns (download):

{
  "action": "download",
  "savedTo": "/Users/jake/Downloads/report.pdf",
  "size": 76292,
  "filename": "report.pdf"
}

Convenience methods: Use context.machine.upload(path) and context.machine.download(url, savePath) instead of calling execute directly.

---

Error Codes

Error	Description
MACHINE_OFFLINE	No machine is currently connected
MACHINE_TIMEOUT	Machine didn't respond within 60 seconds
Capability not found or is disabled	The requested capability is not available on the machine
Plugin does not declare machine capability	The plugin's manifest doesn't include this capability
User has not approved machine capability	The user hasn't approved this capability for the plugin