Computers and teams
Your computers, unattended access on this computer, teams and your remote use this month.
| Command | Description |
|---|---|
cua host | Unattended access to this computer (setup, status, stop, start, remove). |
cua host setup | Set this computer up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port. |
cua host pair | Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer. |
cua host config | Show or change what this computer shares: its own desktop, and whether it creates Spaces for your other devices. |
cua host cache | What the repo cache holds, and empty it. |
cua host cache status | What the repo cache holds: repositories, size and what the last week saved. |
cua host cache fill | Copy one public repository into the cache now, instead of when a Space first clones it (or bring a copy up to date). |
cua host cache clear | Delete every repository the cache holds. |
cua host status | Show whether this computer is set up, the service, and who is connected. |
cua host stop | Stop sharing: disconnect everyone and refuse new connections. |
cua host start | Start sharing again after stop. |
cua host share | Share a relay computer (this one, or --machine) with people in your team (id or verified email). |
cua host unshare | Stop sharing a relay computer with accounts; their open connections are cut. |
cua host migrate | macOS: move the host service into the Cua Spaces app, as its "Cua Spaces Helper" login item, from the LaunchAgent that older versions installed. |
cua host remove | Unregister from the relay, uninstall the service and delete the host configuration (asks first). |
cua devices | This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what. |
cua devices status | This device: enrolled, waiting for approval, or not enrolled. |
cua devices enroll | Enroll this device. |
cua devices approve | Approve a new device (or re-verify an expired one) from this enrolled device, by the code it shows or by its id. |
cua devices ls | Your signed-in machines and their state. |
cua devices rename | Rename a device. |
cua devices revoke | Revoke a device: it can no longer list or reach your computers. |
cua devices audit | Who accessed what, and when: enrollments, device sessions, computer access (yours and by accounts you share with), sharing changes. |
cua team | Teams (organizations of your cua.ai account) share computers with every member and their agents. |
cua team create | Create a team; you are its owner. |
cua team ls | Your teams. |
cua team show | A team: plan, members, computers, open invites and devices. |
cua team invite | Invite someone by email: cua.ai emails them an invitation. |
cua team join | After accepting an emailed invitation: take the role it offered. |
cua team leave | Leave a team. |
cua team remove-member | Remove a member (owner or admin; admins cannot remove admins). |
cua team set-role | Make a member an admin, or an admin a member (owner). |
cua team devices | Member devices and whether they may open team computers. |
cua team approve | Approve a member device so it can open team computers. |
cua team deny | Decline a member device (it can no longer open team computers). |
cua team request | Ask the team's admins to approve this device. |
cua team add-machine | Make a Space (or a computer you host) a team computer: every member and their agents see it and can open it. |
cua team remove-machine | Take a computer off the team. |
cua team audit | The team's audit log. |
cua team delete | Delete a team (owner; cancel its subscription first). |
cua usage | Your remote use this month: computers in use at once, remote hours, and your plan. |
Every command also accepts the global options.
cua host#
Unattended access to this computer (setup, status, stop, start, remove).
cua host [OPTIONS] <COMMAND>cua host setup#
Set this computer up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port. By default it shares this computer's desktop and, on a computer set up for the first time through the relay, provides Spaces to your devices (a host in your pool: cua run jobs and --on auto Spaces can run here, within its limits). --share picks what it shares: desktop, spaces (its own desktop stays private), both or none; cua host config changes it later. A computer set up before keeps what it provides. Running it again with the same options changes nothing (a stopped service starts again).
cua host setup [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--pair | string | Join with a one-time pairing code (or add-machine link) made in the Cua Spaces app or with cua host pair, instead of signing in here. The computer joins the account (or team) that made it. | |
--name | string | Display name (default: the host name). | |
--allow | string | Also allow this account (id or email). Repeatable. | |
--driver-bin | path | cua-spacesd binary (default $CUA_SPACESD_BIN, a bundled one, or the release download). | |
--runner | string | auto | auto | systemd | launchd | app-helper | windows-task | process. On a Mac with the Cua Spaces app, auto is app-helper: the service runs as the app's own login item ("Cua Spaces"). |
--share | desktop | spaces | both | none | What this computer shares: its own desktop (screen, input, shell, files), the Spaces it creates for your enrolled devices (Lume macOS VMs, Docker Linux containers), both, or neither (refused). Default: the desktop, plus Spaces on a new relay setup; a computer set up before keeps what it provides. | |
--max-spaces | integer | Provided Spaces at once (default 4; 0: no limit). | |
--remote | boolean | false | When sign-in is needed, use a device code to approve it in a browser on another computer. The account session is not saved. |
--dedicated | boolean | false | This computer exists only for Cua work (a cloud instance made for it; cua cloud add aws sets its hosts up this way): jobs may run in its own Space (kind = "machine"), with its GPU and drivers as they are. Never on a computer you also use: there jobs run in macOS VMs or containers. |
Examples
# Join the cua.ai relay as your account (shares this desktop and provides Spaces to your devices)
cua host setup
# Share this desktop only
cua host setup --share desktop
# A spare computer: do not share its desktop, run Spaces for your devices
cua host setup --share spaces --name "Mac mini (spare)"
# Add this computer with a one-time code from the Cua Spaces app (Add a computer) or `cua host pair`: no sign-in needed here
cua host setup --pair K7QM-4XPB-2RHDcua host pair#
Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer. Codes work once and expire (30 minutes by default). Run from an enrolled device.
cua host pair [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--team | string | Add the computer to this team (id, alias or name; owner or admin): waits until the computer joins, then makes it a team computer. | |
--name | string | Name the computer gets (default: its own host name). | |
--expires | integer | 30 | Minutes until the code expires (1 to 1440). |
--revoke | string | Revoke an unused code by id (pc_…). | |
--no-wait | boolean | false | With --team: print the code and exit instead of waiting; add the computer later with cua team add-machine <team> relay:<id>. |
--list | boolean | false | List your codes (used, unused, revoked, expired) instead. |
Examples
cua host pair
cua host pair --name build-box --expires 60
cua host pair --list
cua host pair --revoke pc_0123456789abcdef
# Add the computer to a team: waits for it to join, then adds it
cua host pair --team AIGIScua host config#
Show or change what this computer shares: its own desktop, and whether it creates Spaces for your other devices.
cua host config [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--desktop | on | off | Share this computer's own desktop: on | off. | |
--provide-spaces | on | off | Create Spaces for your enrolled devices: on | off. | |
--max-spaces | integer | Provided Spaces at once (0: no limit). | |
--max-macos-vms | integer | macOS VMs at once, 0 to 2 (Apple's license allows two per Mac). | |
--max-memory | integer | Memory in GB the Spaces other machines create here may use in total (0: no limit). | |
--max-disk | integer | Disk in GB the Spaces other machines create here may use in total (0: no limit). | |
--max-run-time | integer | Minutes a Space created here by another machine may run before it is stopped (0: no limit). | |
--repo-cache | on | off | The repo cache: on | off. It keeps verified copies of public git repositories on this machine so a repeat git clone in a Space starts from one (never private repositories, never anything off this machine's disk). | |
--repo-cache-size | string | The most disk the repo cache may use, in GB (auto: the smaller of 5 GB and a tenth of the free disk). The least recently used repositories go first. |
Examples
cua host config
# Stop sharing this desktop; keep providing Spaces
cua host config --desktop off --provide-spaces on
cua host config --max-spaces 6
# Give the Spaces other machines create here at most 32 GB of memory and 200 GB of disk in total, and stop each after 8 hours (0: no limit)
cua host config --max-memory 32 --max-disk 200 --max-run-time 480
# Keep no copies of public git repositories on this machine, or at most 2 GB
cua host config --repo-cache off
cua host config --repo-cache on --repo-cache-size 2cua host cache#
What the repo cache holds, and empty it.
cua host cache [OPTIONS] <COMMAND>cua host cache status#
What the repo cache holds: repositories, size and what the last week saved.
cua host cache status [OPTIONS]Examples
cua host cache statuscua host cache fill#
Copy one public repository into the cache now, instead of when a Space first clones it (or bring a copy up to date). A repository that needs a sign-in is never cached.
cua host cache fill [OPTIONS] <URL>| Argument | Type | Default | Description |
|---|---|---|---|
<URL> | string | required | The repository's https address. |
Examples
cua host cache fill https://github.com/vitejs/vitecua host cache clear#
Delete every repository the cache holds. They are copied again the next time a Space clones them.
cua host cache clear [OPTIONS]Examples
cua host cache clearcua host status#
Show whether this computer is set up, the service, and who is connected.
cua host status [OPTIONS]Examples
cua host statuscua host stop#
Stop sharing: disconnect everyone and refuse new connections.
cua host stop [OPTIONS]Examples
cua host stopcua host start#
Start sharing again after stop.
cua host start [OPTIONS]Examples
cua host startcua host share#
Share a relay computer (this one, or --machine) with people in your team (id or verified email). Run from an enrolled device; every change is in the owner's audit log (cua devices audit).
cua host share [OPTIONS] <WHO>...| Argument | Type | Default | Description |
|---|---|---|---|
<WHO>... | string | required | Accounts to add. Repeatable. Repeatable. |
| Flag | Type | Default | Description |
|---|---|---|---|
--machine | string | Computer id (default: this computer). Alias: --computer. | |
--yes | boolean | false | Do not ask for confirmation. |
Examples
cua host share friend@example.com
cua host share friend@example.com --machine 0123abcd4567ef89 --yescua host unshare#
Stop sharing a relay computer with accounts; their open connections are cut.
cua host unshare [OPTIONS] <WHO>...| Argument | Type | Default | Description |
|---|---|---|---|
<WHO>... | string | required | Accounts to remove. Repeatable. Repeatable. |
| Flag | Type | Default | Description |
|---|---|---|---|
--machine | string | Computer id (default: this computer). Alias: --computer. |
Examples
cua host unshare friend@example.comcua host migrate#
macOS: move the host service into the Cua Spaces app, as its "Cua Spaces Helper" login item, from the LaunchAgent that older versions installed. This machine keeps its id, registration and Spaces; if the helper does not take over, the old service is put back. macOS then asks once for Screen Recording and Accessibility for Cua Spaces Helper.
cua host migrate [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--force | boolean | false | Try again even if a move failed before with this version. |
Examples
cua host migrate
# Try again after a move that was rolled back
cua host migrate --forcecua host remove#
Unregister from the relay, uninstall the service and delete the host configuration (asks first).
cua host remove [OPTIONS]| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--force | -f | boolean | false | Skip the confirmation prompt. Required when there is no terminal to ask on (scripts, agents): without it nothing is removed. |
--uninstalling | boolean | false | For an uninstall of Cua Spaces: turns off the Spaces this computer provides and takes them off the relay too, instead of refusing while it provides any. The Spaces and their data stay on this computer. |
Examples
cua host remove
# Without the prompt (required in scripts and agents)
cua host remove --forcecua devices#
This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what.
cua devices [OPTIONS] <COMMAND>Examples
cua devices enroll
cua devices approve K7QX-M2RP
cua devices ls
cua devices auditcua devices status#
This device: enrolled, waiting for approval, or not enrolled.
cua devices status [OPTIONS]Examples
cua devices statuscua devices enroll#
Enroll this device. Right after a fresh cua auth login it enrolls at once (and replaces this computer's older device key, if any); otherwise it shows a one-time code to approve from an enrolled device (cua devices approve <code> or the Cua Spaces app).
cua devices enroll [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | Display name (default: the host name). | |
--wait | boolean | false | Wait (up to 10 minutes) until an enrolled device approves. |
Examples
cua devices enroll
cua devices enroll --name "work laptop" --waitcua devices approve#
Approve a new device (or re-verify an expired one) from this enrolled device, by the code it shows or by its id.
cua devices approve [OPTIONS] [CODE]| Argument | Type | Default | Description |
|---|---|---|---|
<CODE> | string | optional | The one-time code the new device shows, or its device id (dev_…, from cua devices ls). |
| Flag | Type | Default | Description |
|---|---|---|---|
--device | string | Or the device id (cua devices ls). | |
--yes | boolean | false | Do not ask for confirmation. |
Examples
cua devices approve K7QX-M2RP
cua devices approve dev_0123456789abcdef01234567cua devices ls#
Your signed-in machines and their state.
cua devices ls [OPTIONS]Alias: cua devices list.
Examples
cua devices ls
cua devices ls --jsoncua devices rename#
Rename a device.
cua devices rename [OPTIONS] <ID> <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<ID> | string | required | Device id. |
<NAME> | string | required | New name. |
Examples
cua devices rename dev_0123456789abcdef01234567 "work phone"cua devices revoke#
Revoke a device: it can no longer list or reach your computers.
cua devices revoke [OPTIONS] <ID>| Argument | Type | Default | Description |
|---|---|---|---|
<ID> | string | required | Device id. |
| Flag | Type | Default | Description |
|---|---|---|---|
--yes | boolean | false | Do not ask for confirmation. |
Examples
cua devices revoke dev_0123456789abcdef01234567cua devices audit#
Who accessed what, and when: enrollments, device sessions, computer access (yours and by accounts you share with), sharing changes.
cua devices audit [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--limit | integer | 50 | Newest events to show. |
Examples
cua devices audit
cua devices audit --limit 20 --jsoncua team#
Teams (organizations of your cua.ai account) share computers with every member and their agents. Owners and admins invite by email, approve member devices and add computers.
cua team [OPTIONS] <COMMAND>Examples
cua team create AIGIS
cua team invite AIGIS dillon@example.com
cua team add-machine AIGIS local:build-box
cua team approve AIGIS dev_0123456789abcdef01234567
cua team show AIGIScua team create#
Create a team; you are its owner. Buy Teams for it at app.cua.ai to add computers.
cua team create [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Team name. |
Examples
cua team create "AIGIS"cua team ls#
Your teams.
cua team ls [OPTIONS]Alias: cua team list.
Examples
cua team ls
cua team ls --jsoncua team show#
A team: plan, members, computers, open invites and devices.
cua team show [OPTIONS] <TEAM>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
Examples
cua team show AIGIScua team invite#
Invite someone by email: cua.ai emails them an invitation. Manage invites at app.cua.ai/team.
cua team invite [OPTIONS] <TEAM> <EMAIL>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
<EMAIL> | string | required | Their email. |
| Flag | Type | Default | Description |
|---|---|---|---|
--role | member | admin | member | member or admin (only the owner invites admins). |
Examples
cua team invite AIGIS dillon@example.com
cua team invite AIGIS ops@example.com --role admincua team join#
After accepting an emailed invitation: take the role it offered. Run cua auth login first so your session lists the team.
cua team join [OPTIONS] <TEAM>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
Examples
cua team join AIGIScua team leave#
Leave a team.
cua team leave [OPTIONS] <TEAM>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
Examples
cua team leave AIGIScua team remove-member#
Remove a member (owner or admin; admins cannot remove admins).
cua team remove-member [OPTIONS] <TEAM> <WHO>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
<WHO> | string | required | Their email or account id. |
Examples
cua team remove-member AIGIS bob@example.comcua team set-role#
Make a member an admin, or an admin a member (owner).
cua team set-role [OPTIONS] <TEAM> <WHO> <ROLE>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
<WHO> | string | required | Their email or account id. |
<ROLE> | member | admin | required | member or admin. |
Examples
cua team set-role AIGIS bob@example.com admincua team devices#
Member devices and whether they may open team computers.
cua team devices [OPTIONS] <TEAM>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
Examples
cua team devices AIGIScua team approve#
Approve a member device so it can open team computers.
cua team approve [OPTIONS] <TEAM> <DEVICE>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
<DEVICE> | string | required | Device id (cua team devices). |
Examples
cua team approve AIGIS dev_0123456789abcdef01234567cua team deny#
Decline a member device (it can no longer open team computers).
cua team deny [OPTIONS] <TEAM> <DEVICE>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
<DEVICE> | string | required | Device id. |
Examples
cua team deny AIGIS dev_0123456789abcdef01234567cua team request#
Ask the team's admins to approve this device.
cua team request [OPTIONS] <TEAM>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
Examples
cua team request AIGIScua team add-machine#
Make a Space (or a computer you host) a team computer: every member and their agents see it and can open it. Macs, Linux and Windows computers all can. Each Space is added on its own: adding a host does not add the Spaces it provides.
cua team add-machine [OPTIONS] <TEAM> <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
<SPACE> | string | required | Space id or name (relay:<id> for a computer you host). |
| Flag | Type | Default | Description |
|---|---|---|---|
--yes | boolean | false | Confirm without a prompt. |
Examples
cua team add-machine AIGIS local:build-box
cua team add-machine AIGIS relay:0123abcd4567ef89 --yescua team remove-machine#
Take a computer off the team.
cua team remove-machine [OPTIONS] <TEAM> <COMPUTER>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
<COMPUTER> | string | required | The computer (relay:<id> or its id, as cua team show lists it). |
Examples
cua team remove-machine AIGIS relay:0123abcd4567ef89cua team audit#
The team's audit log. Audit export is coming soon; for now see the account app (app.cua.ai).
cua team audit [OPTIONS] <TEAM>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
| Flag | Type | Default | Description |
|---|---|---|---|
--limit | integer | 50 | Newest events to show (when export arrives). |
Examples
cua team audit AIGIScua team delete#
Delete a team (owner; cancel its subscription first). Its computers stay yours.
cua team delete [OPTIONS] <TEAM>| Argument | Type | Default | Description |
|---|---|---|---|
<TEAM> | string | required | Team id, alias or name. |
| Flag | Type | Default | Description |
|---|---|---|---|
--yes | boolean | false | Do not ask for confirmation. |
Examples
cua team delete AIGIS --yescua usage#
Your remote use this month: computers in use at once, remote hours, and your plan. Remote hours are time spent using your computers from somewhere else; using a computer from itself is free.
cua usage [OPTIONS]Examples
cua usage
cua usage --jsonExit codes#
| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure, or cua do reported an error. |
2 | Invalid argument, or an ambiguous sandbox name (qualify it: local:NAME). |
3 | Not found: sandbox, window, skill or image (or an image not published yet). |
4 | Not supported, or not configured (for example no provider credentials). |
5 | No cua-spacesd answered, or a transport failure. |
6 | Unauthenticated or permission denied (by Cua or your cloud account). |
7 | Not enough free disk space (see cua cache). |
8 | No room on the machine: its VMs are at their memory or CPU limit, or it is low on memory. |
130 | Cancelled (Ctrl-C during a create): what it made was removed. |