CUA Auto

0.1.2 · active · verified Sun Apr 12

cua-auto is the Python client library for interacting with the CUA computer server, enabling cross-platform automation of mouse, keyboard, screen, window, clipboard, and shell operations. It is currently at version 0.1.2, with the larger CUA ecosystem seeing more frequent updates across its modular components (server, sandbox).

Warnings

gotcha The `cua-auto` library is a client to the `cua-computer-server`. It will not function standalone; you must have a `cua-computer-server` running and accessible from the client for any automation to occur.
Fix: Ensure `cua-computer-server` is installed and running on a reachable host and port before attempting to use `cua-auto`. Refer to the CUA project documentation for server setup.
gotcha Cross-platform automation libraries often require specific operating system permissions (e.g., accessibility services, screen recording) to function correctly. Without these, certain automation tasks may fail or be limited.
Fix: Consult your operating system's documentation and the CUA project's specific setup guides for enabling necessary permissions (e.g., macOS Accessibility, Linux X11 permissions).
gotcha Telemetry might be enabled by default in the CUA ecosystem, which includes the `cua-computer-server` that `cua-auto` connects to. Users concerned about data collection should explicitly opt out.
Fix: Check the `cua-computer-server` documentation for instructions on how to disable telemetry, which typically involves setting an environment variable or configuration option.
gotcha The `cua-auto` library has specific Python version requirements, currently supporting Python 3.11, 3.12, and 3.13. Running it with unsupported versions (e.g., Python 3.10 or 3.14+) may lead to installation errors or unexpected runtime behavior.
Fix: Ensure your development environment uses a supported Python version (`>=3.11, <3.14`). Consider using virtual environments to manage Python versions.

Install

pip install cua-auto Install stable version

Imports

CuaClient
```
from cua_auto import CuaClient
```

Quickstart

This quickstart demonstrates connecting to a CUA computer server and performing basic mouse and keyboard actions. It's crucial to have a `cua-computer-server` instance running on the specified host and port for this client library to function.

import os
from cua_auto import CuaClient

# The CuaClient connects to a running CUA computer server.
# Ensure 'cua-computer-server' is running on the specified host and port.
# For local testing, you might need to start it separately.
host = os.environ.get("CUA_SERVER_HOST", "localhost")
port = int(os.environ.get("CUA_SERVER_PORT", 1337))

try:
    client = CuaClient(host=host, port=port)
    print(f"Connected to CUA server at {host}:{port}")

    # Example: Get screen size
    screen_size = client.screen.get_size()
    print(f"Screen size: {screen_size.width}x{screen_size.height}")

    # Example: Move mouse relative to current position
    client.mouse.move_relative(100, 50)
    print("Moved mouse by 100, 50 pixels.")

    # Example: Type text
    client.keyboard.type("Hello from cua-auto!")
    print("Typed 'Hello from cua-auto!'.")

except ConnectionRefusedError:
    print(f"Error: Connection to CUA server at {host}:{port} refused.")
    print("Please ensure the 'cua-computer-server' is running and accessible.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →