Cua Docs

Your first Cua Driver Python app

Import Cua Driver as a same-process Python SDK and inspect the desktop.

In this tutorial, you will import Cua Driver into a Python application, start a session, and read the desktop size. The driver runs in your Python process; you do not need to start a daemon.

Before you begin#

You need Python 3.10 or newer and a supported interactive macOS, Windows, or Linux desktop. On macOS, the Python host needs Accessibility and Screen Recording permission for the actions it performs.

Create a virtual environment and install the published package:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install cua-driver

Create the application#

Save this as first_driver.py:

import asyncio
 
from cua_driver import (
    CaptureScope,
    CuaDriver,
    EndSessionInput,
    GetScreenSizeInput,
    StartSessionInput,
)
 
 
async def main() -> None:
    driver = CuaDriver.create()
    session = "first-sdk-app"
 
    await driver.start_session(
        StartSessionInput(
            session=session,
            capture_scope=CaptureScope.DESKTOP,
        )
    )
    try:
        metadata = await driver.metadata()
        screen = await driver.get_screen_size(
            GetScreenSizeInput(session=session)
        )
        print(f"cua-driver {metadata.driver_version}")
        print(screen.text)
    finally:
        await driver.end_session(EndSessionInput(session=session))
        await driver.shutdown()
 
 
asyncio.run(main())

Run it:

python first_driver.py

The program prints the loaded driver version and the desktop dimensions. It also demonstrates the lifecycle every SDK application should own: create the runtime, start and end its sessions, then await shutdown().

Next steps#