Skip to content

feat: add cua-cli Python package with local image management - #998

Open
f-trycua wants to merge 6 commits into
mainfrom
cua-cli
Open

feat: add cua-cli Python package with local image management#998
f-trycua wants to merge 6 commits into
mainfrom
cua-cli

Conversation

@f-trycua

@f-trycua f-trycua commented Feb 4, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR adds the cua-cli Python package with local image management capabilities, versioned documentation infrastructure, and several codebase improvements.

1. New cua-cli Python package (libs/python/cua-cli/)

A unified CLI for CUA platform management, installable as cua command:

  • cua image create <platform> — Create local VM/container images (linux-docker, linux-qemu, windows-qemu, android-qemu, macos-lume)
  • cua image clone <name> <new-name> — Clone an existing local image
  • cua image shell <name> — Launch interactive shell into a local image (Docker overlay or QEMU)
  • cua image info <name> — Show detailed info about a local image
  • cua image list --local — List locally registered images
  • cua image delete --local <name> — Delete a local image
  • cua platform list — Show all supported platforms and their status
  • cua platform info <platform> — Detailed platform info with dependency checks

Supporting modules:

  • cua_cli/utils/paths.py — XDG Base Directory helpers (~/.local/share/cua/, ~/.local/state/cua/)
  • cua_cli/utils/docker.py — Port allocation, Docker overlay copy utilities
  • cua_cli/utils/registry.py — Image registry JSON management (images.json)
  • cua_cli/commands/platform.py — PLATFORMS configuration dict + dependency checks
  • Full test suite: 163 tests passing

2. Deprecation wrappers in cua-bench

  • cb image and cb platform now delegate to cua-cli with yellow deprecation warnings
  • Graceful fallback to local implementations if cua-cli is not installed
  • cua-cli is not a hard dependency (not on PyPI yet)

3. Versioned docs pipeline

  • scripts/docs-generators/generate-versioned-docs.ts — Generates versioned API reference docs from Python SDK source
  • scripts/docs-generators/generate-changelog.ts — Generates changelogs from git tags
  • scripts/docs-generators/python-sdk.ts — Python SDK doc extraction
  • scripts/docs-generators/extract_python_docs.py — AST-based Python docstring extractor
  • Versioned docs added for: agent-sdk (v0.3–v0.7), computer-sdk (v0.3–v0.5), lume (v0.2), CLI
  • Changelogs generated for agent-sdk, computer-sdk, desktop-sandbox

4. Docs UI changes

  • Version selector component (docs/src/components/version-selector.tsx) for navigating between SDK versions
  • Updated custom header component
  • Restructured get-started guide (quickstart, self-hosted sandboxes)
  • Removed old cloud-cli reference (replaced by new CLI reference)
  • Removed cuabot docs section

5. Agent SDK refactor (libs/python/agent/)

  • New agent/core/ module with base classes, factory, tools, telemetry, callbacks
  • New agent/providers/ module with provider-specific implementations (Anthropic, OpenAI, Omni, UITars)
  • Updated version to 0.7.22

6. CI/CD

  • New: cd-py-cli.yml — Publishing workflow for cua-cli to PyPI on cli-v* tags
  • Updated existing CD workflows for consistency
  • Removed cuabot-related CI/CD workflows

7. Other changes

  • New lume Swift files: ClipboardWatcher.swift, SSH.swift, SSHClient.swift, SSHErrors.swift
  • New unattended install configs for macOS Sequoia and Tahoe
  • Computer SDK telemetry module
  • Removed deb/ and debb/ debug screenshot directories
  • Removed stray docs/ref={function} junk file

Test plan

  • All 163 cua-cli tests pass (python -m pytest tests/)
  • CLI argument parsing verified for all new commands
  • CI: computer, computer-server, core, som, mcp-server tests pass
  • Manual test: cua platform list shows platform status
  • Manual test: cua image create linux-docker pulls and registers image
  • Manual test: cb image list shows deprecation warning and delegates

Known CI issues (pre-existing, not from this PR)

  • Test agent: 2 tests in test_tool_resolution.py fail due to agent core refactor (BrowserTool protocol changes)
  • Lume: MockVNCService doesn't conform to updated VNCService protocol (SSH changes)

@vercel

vercel Bot commented Feb 4, 2026

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview, Comment Feb 8, 2026 11:12pm

Request Review

@sentry

sentry Bot commented Feb 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@coderabbitai

coderabbitai Bot commented Feb 8, 2026

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)
  • rabbit

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

  • 🔍 Trigger a full review
✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch cua-cli

Comment @coderabbitai help to get the list of available commands and usage tips.

- Add `cua image create/clone/shell/info` commands for local VM image management
- Add `cua platform list/info` commands for platform configuration
- Add image registry, XDG paths, and Docker utilities to cua-cli
- Add deprecation wrappers in cua-bench so `cb image` and `cb platform` delegate to cua-cli
- Add versioned docs pipeline with changelog generation
- Add docs version selector component
- Remove debug screenshot directories (deb/, debb/)
- Fix isort and prettier formatting across all packages
- Replace manually curated computer-sdk and agent-sdk index pages with
  auto-generated content from Python source via Griffe
- Add includeSubmodules filter to doc generator to control which
  submodules appear (callbacks, tools, types for agent; interface,
  models, tracing, helpers, diorama_computer for computer)
- Add @trycua/cli deprecation notice to CLI docs
- Hide MCP Server section from sidebar navigation
- Fix Jupyter Notebook callout newline rendering in hud.mdx and
  agent-loops.mdx
- Add icon to Claude Code examples section
- Add permanent redirects for old /api URLs
- Update versioned doc "View latest" links
@f-trycua

f-trycua commented Feb 8, 2026

Copy link
Copy Markdown
Collaborator Author

Superseded by a clean PR from cua-cli-clean branch (this PR had accumulated ~23 extra commits from other squash-merged PRs).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant