iOS Agent

# List all registered devices in your CMDOP workspace
cmdop machines
 
# Output:
# HOSTNAME         TYPE     STATUS
# macbook-pro      desktop  connected
# prod-server      server   connected
# marks-iphone     ios      connected
 
# Open a terminal session to the iPhone device
cmdop terminal marks-iphone
 
# Note: No shell, but file operations work

from cmdop import AsyncCMDOPClient
 
# Initialize a remote client session with your API key
async with AsyncCMDOPClient.remote(api_key="cmd_xxx") as client:
    # Switch the terminal context to the iPhone device
    await client.terminal.set_machine("marks-iphone")
 
    # List all files at the root of the iPhone sandbox
    files = await client.files.list("marks-iphone", "/")
    print(./files)
 
    # Retrieve device telemetry: battery level, free storage, etc.
    info = await client.system.info("marks-iphone")
    print(f"Battery: {info.battery_percent}%")
    print(f"Storage: {info.storage_free_gb} GB free")

from pydantic import BaseModel
 
# Pydantic model describing the fields returned by system.info()
class DeviceInfo(BaseModel):
    device_name: str
    model: str
    os_version: str
    battery_percent: int
    battery_charging: bool
    storage_total_gb: float
    storage_free_gb: float
    wifi_connected: bool
    cellular_connected: bool
 
# Fetch real-time device info from the connected iPhone
info = await client.system.info("marks-iphone")
# DeviceInfo(
#   device_name="Mark's iPhone",
#   model="iPhone 15 Pro",
#   os_version="17.4",
#   battery_percent=78,
#   battery_charging=False,
#   storage_total_gb=256.0,
#   storage_free_gb=45.2,
#   ...
# )

marks-iphone:/
├── Documents/          # App documents (read/write)
├── Library/            # App library (read/write)
├── tmp/                # Temporary files (read/write)
└── Photos/             # Photo library (read only, with permission)

# List all files in the Documents directory
files = await client.files.list("marks-iphone", "/Documents")
 
# Read the contents of a text file from the device
content = await client.files.read("marks-iphone", "/Documents/notes.txt")
 
# Write a JSON configuration file to the device
await client.files.write(
    "marks-iphone",
    "/Documents/config.json",
    '{"setting": "value"}'
)
 
# Download a database file from the device to the local machine
await client.files.download(
    "marks-iphone",
    "/Documents/data.sqlite",
    "./data.sqlite"
)
 
# Upload a local PDF to the device's Documents folder
await client.files.upload(
    "./report.pdf",
    "marks-iphone",
    "/Documents/report.pdf"
)

# List all photos in the photo library (requires user-granted permission)
photos = await client.files.list("marks-iphone", "/Photos")
 
# Download a specific photo by filename to the local machine
await client.files.download(
    "marks-iphone",
    "/Photos/IMG_1234.jpg",
    "./photo.jpg"
)

# Attempting shell execution on iOS will raise an error
output, code = await client.terminal.execute("ls -la")
# Error: Shell not available on iOS devices

# Accessing sandbox paths works normally
files = await client.files.list("marks-iphone", "/Documents")
 
# Accessing paths outside the sandbox is denied by iOS
files = await client.files.list("marks-iphone", "/var/mobile")
# Error: Access denied

# Long operations may be interrupted when the app is suspended
# Use push wake for reliability (see Push Wake guide)

async def backup_photos():
    # List every photo in the device's photo library
    photos = await client.files.list("marks-iphone", "/Photos")
 
    # Download each photo to a local backup directory
    for photo in photos:
        await client.files.download(
            "marks-iphone",
            photo.path,
            f"./backup/{photo.name}"
        )
        print(f"Backed up: {photo.name}")
 
await backup_photos()

async def sync_documents():
    # Get the list of local and remote document filenames
    local_docs = os.listdir("./docs")
    remote_docs = await client.files.list("marks-iphone", "/Documents")
 
    # Upload any local file that doesn't already exist on the device
    for doc in local_docs:
        if doc not in [r.name for r in remote_docs]:
            await client.files.upload(
                f"./docs/{doc}",
                "marks-iphone",
                f"/Documents/{doc}"
            )
            print(f"Synced: {doc}")
 
await sync_documents()

async def monitor_battery():
    while True:
        # Poll device info to read current battery level
        info = await client.system.info("marks-iphone")
 
        # Alert when battery drops below 20% and is not charging
        if info.battery_percent < 20 and not info.battery_charging:
            send_notification("iPhone battery low!")
 
        await asyncio.sleep(300)  # Check every 5 minutes

# Request a screenshot (the CMDOP app must be in the foreground)
screenshot = await client.system.screenshot("marks-iphone")
 
# Save the screenshot bytes to a local PNG file
with open("screenshot.png", "wb") as f:
    f.write(screenshot)