Files, teleport and keys

Cua Volume files and sharing, moving an app session into a sandbox, and the Cua Keyvault.

Command	Description
`cua volume`	Cua Volume: the versioned volume every Space and agent shares (public/, agents/<agent>/, spaces/<space>/), its grants and audit.
`cua volume ls`	List a folder (default: the root).
`cua volume cat`	Print a file (or one of its versions) to stdout.
`cua volume put`	Write a file from a local file, or from stdin with `-`.
`cua volume rm`	Delete a file (its history stays).
`cua volume history`	A file's versions, newest first.
`cua volume restore`	Make an old version current again (a new version).
`cua volume grant`	Let an agent or a Space read (or, with --rw, write) a folder beyond its defaults.
`cua volume revoke`	Revoke a grant.
`cua volume grants`	The grants (live ones; --all includes expired and revoked).
`cua volume requests`	Access requests agents filed, waiting for you.
`cua volume approve`	Turn a request into a grant.
`cua volume deny`	Decline a request.
`cua volume audit`	The audit log, newest first, and whether its hash chain verified.
`cua volume mount`	Show the drive as a volume (Finder on macOS, FUSE on Linux).
`cua volume unmount`	Turn the volume off (files still uploading land first).
`cua volume status`	The volume, sync across devices, and the block cache.
`cua volume config`	Which store the drive uses (fs, s3).
`cua volume config show`	The backend and bucket settings in effect (never keys).
`cua volume config set`	Choose the backend.
`cua volume config set-keys`	Save S3 keys in the credential store: the access key id and the secret, one per line on stdin.
`cua teleport`	Move a desktop app session (tabs, profile, sign-in) into a sandbox.
`cua teleport providers`	List the apps this machine can teleport (JSON).
`cua teleport manifest`	Describe what teleporting an app would move (JSON).
`cua teleport push`	Teleport an app session into a sandbox.
`cua keyvault`	The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals.
`cua keyvault status`	Whether the Keyvault exists and is unlocked, and which protectors (Touch ID with the OS key store, a passphrase) the daemon can use.
`cua keyvault init`	Create the Keyvault and print its recovery key once.
`cua keyvault unlock`	Unlock the Keyvault with the OS key store, or with its passphrase.
`cua keyvault lock`	Lock the Keyvault (unlocking needs the OS key store or the passphrase again).
`cua keyvault import-passwords`	Import a browser's saved passwords into the Keyvault, one item per site.
`cua keyvault import-session`	Import a signed-in session (cookies, or a single-app session like Slack's) into the Keyvault, without delivering it anywhere.
`cua keyvault requests`	Requests waiting for your approval (site logins, teleports).
`cua keyvault approve`	Approve a waiting request (the daemon asks for Touch ID or your login password).
`cua keyvault deny`	Decline a waiting request.

Every command also accepts the global options.

`cua volume`#

Cua Volume: the versioned volume every Space and agent shares (public/, agents/<agent>/, spaces/<space>/), its grants and audit. (cua volume still works for one release.).

cua volume [OPTIONS] <COMMAND>

Examples

cua volume ls agents/
cua volume cat agents/ada/memory/MEMORY.md
cua volume put public/rules.md ./rules.md
cua volume grant agent:researcher agents/writer/outputs/
cua volume audit

`cua volume ls`#

List a folder (default: the root).

cua volume ls [OPTIONS] [PATH]

Argument	Type	Default	Description
`<PATH>`	string	optional

Flag	Type	Default	Description
`--as`	string		View the drive as this persistent agent does (`agent:ada` or `ada`).
`--space`	string		With --as: the Space the agent is in (its `spaces/<space>/` folder).

Examples

cua volume ls
cua volume ls agents/ada/
cua volume ls --as agent:ada --space local:work

`cua volume cat`#

Print a file (or one of its versions) to stdout.

cua volume cat [OPTIONS] <PATH>

Argument	Type	Default	Description
`<PATH>`	string	required

Flag	Type	Description
`--version`	string
`--as`	string	View the drive as this persistent agent does (`agent:ada` or `ada`).
`--space`	string	With --as: the Space the agent is in (its `spaces/<space>/` folder).

Examples

cua volume cat agents/ada/memory/MEMORY.md
cua volume cat public/rules.md --version 0001790683200000-1a2b3c4d

`cua volume put`#

Write a file from a local file, or from stdin with -.

cua volume put [OPTIONS] <PATH> <SOURCE>

Argument	Type	Default	Description
`<PATH>`	string	required
`<SOURCE>`	string	required	Local file, or `-` for stdin.

Flag	Type	Default	Description
`--if-etag`	string		Write only if the current version has this etag.
`--as`	string		View the drive as this persistent agent does (`agent:ada` or `ada`).
`--space`	string		With --as: the Space the agent is in (its `spaces/<space>/` folder).
`--create-only`	boolean	`false`	Write only if nothing is at the path yet.

Examples

cua volume put public/rules.md ./rules.md
cua volume put public/rules.md -
cua volume put agents/ada/inbox/brief.md ./brief.md --create-only

`cua volume rm`#

Delete a file (its history stays).

cua volume rm [OPTIONS] <PATH>

Argument	Type	Default	Description
`<PATH>`	string	required

Flag	Type	Description
`--if-etag`	string
`--as`	string	View the drive as this persistent agent does (`agent:ada` or `ada`).
`--space`	string	With --as: the Space the agent is in (its `spaces/<space>/` folder).

Examples

cua volume rm spaces/local-work/scratch.txt

`cua volume history`#

A file's versions, newest first.

cua volume history [OPTIONS] <PATH>

Argument	Type	Default	Description
`<PATH>`	string	required

Flag	Type	Default	Description
`--as`	string		View the drive as this persistent agent does (`agent:ada` or `ada`).
`--space`	string		With --as: the Space the agent is in (its `spaces/<space>/` folder).

Examples

cua volume history agents/ada/memory/MEMORY.md

`cua volume restore`#

Make an old version current again (a new version).

cua volume restore [OPTIONS] <PATH> <VERSION>

Argument	Type	Default	Description
`<PATH>`	string	required
`<VERSION>`	string	required

Flag	Type	Default	Description
`--as`	string		View the drive as this persistent agent does (`agent:ada` or `ada`).
`--space`	string		With --as: the Space the agent is in (its `spaces/<space>/` folder).

Examples

cua volume restore agents/ada/memory/MEMORY.md 0001790683200000-1a2b3c4d

`cua volume grant`#

Let an agent or a Space read (or, with --rw, write) a folder beyond its defaults. Asks for Touch ID or your passphrase.

cua volume grant [OPTIONS] <PRINCIPAL> <PREFIX>

Argument	Type	Default	Description
`<PRINCIPAL>`	string	required	`agent:<name>` or `space:<id>`.
`<PREFIX>`	string	required	A folder (ending in /) or one file.

Flag	Type	Default	Description
`--for`	string		Lifetime (`30m`, `2h`, `7d`). Default: until revoked.
`--note`	string		A note shown next to the grant.
`--rw`	boolean	`false`	Read and write (default: read only).

Examples

cua volume grant agent:researcher agents/writer/outputs/
cua volume grant space:local-build public/datasets/ --rw --for 2h

`cua volume revoke`#

Revoke a grant.

cua volume revoke [OPTIONS] <GRANT_ID>

Argument	Type	Default	Description
`<GRANT_ID>`	string	required

Examples

cua volume revoke 5f2c9a0b1d3e4f67

`cua volume grants`#

The grants (live ones; --all includes expired and revoked).

cua volume grants [OPTIONS]

Flag	Type	Default	Description
`--all`	boolean	`false`

Examples

cua volume grants

`cua volume requests`#

Access requests agents filed, waiting for you.

cua volume requests [OPTIONS]

Examples

cua volume requests

`cua volume approve`#

Turn a request into a grant. Asks for Touch ID or your passphrase.

cua volume approve [OPTIONS] <REQUEST_ID>

Argument	Type	Default	Description
`<REQUEST_ID>`	string	required

Flag	Type	Default	Description
`--for`	string

Examples

cua volume approve 5f2c9a0b1d3e4f67
cua volume approve 5f2c9a0b1d3e4f67 --for 1d

`cua volume deny`#

Decline a request.

cua volume deny [OPTIONS] <REQUEST_ID>

Argument	Type	Default	Description
`<REQUEST_ID>`	string	required

Examples

cua volume deny 5f2c9a0b1d3e4f67

`cua volume audit`#

The audit log, newest first, and whether its hash chain verified.

cua volume audit [OPTIONS]

Flag	Type	Default	Description
`--limit`	integer	`50`

Examples

cua volume audit
cua volume audit --limit 200 --json

`cua volume mount`#

Show the drive as a volume (Finder on macOS, FUSE on Linux). Off until turned on; stays on across restarts.

cua volume mount [OPTIONS]

Examples

cua volume mount
cua volume mount --json

`cua volume unmount`#

Turn the volume off (files still uploading land first).

cua volume unmount [OPTIONS]

Examples

cua volume unmount

`cua volume status`#

The volume, sync across devices, and the block cache.

cua volume status [OPTIONS]

Examples

cua volume status
cua volume status --json

`cua volume config`#

Which store the drive uses (fs, s3).

cua volume config [OPTIONS] <COMMAND>

`cua volume config show`#

The backend and bucket settings in effect (never keys).

cua volume config show [OPTIONS]

Examples

cua volume config show

`cua volume config set`#

Choose the backend. Keys are never arguments: see set-keys.

cua volume config set [OPTIONS] --backend <BACKEND>

Flag	Type	Default	Description
`--backend`	string	required	`fs` (default) or `s3`.
`--endpoint`	string
`--region`	string
`--bucket`	string
`--root`	string		A key prefix every drive key lives under.
`--path-style`	boolean	`false`

Examples

cua volume config set --backend fs
cua volume config set --backend s3 --endpoint http://127.0.0.1:9000 --bucket cua-volume --path-style

`cua volume config set-keys`#

Save S3 keys in the credential store: the access key id and the secret, one per line on stdin.

cua volume config set-keys [OPTIONS]

Examples

cua volume config set-keys

`cua teleport`#

Move a desktop app session (tabs, profile, sign-in) into a sandbox.

cua teleport [OPTIONS] <COMMAND>

`cua teleport providers`#

List the apps this machine can teleport (JSON).

cua teleport providers [OPTIONS]

Examples

cua teleport providers

`cua teleport manifest`#

Describe what teleporting an app would move (JSON).

cua teleport manifest [OPTIONS] --app <APP>

Flag	Type	Default	Description
`--app`	string	required	App: a bundle id or app name ("com.google.Chrome", "Slack", "claude-code").
`--scope`	string	`full`	`tabs` (open tabs and session state) or `full` (the whole profile).
`--profile`	string		Chrome profile to capture: a name ("Profile 1") or a path.
`--display-name`	string		Display name for the app (UI only).

Examples

cua teleport manifest --app com.google.Chrome --scope tabs

`cua teleport push`#

Teleport an app session into a sandbox.

cua teleport push [OPTIONS] --app <APP>

Flag	Short	Type	Default	Env var	Description
`--app`		string	required		App: a bundle id or app name ("com.google.Chrome", "Slack", "claude-code").
`--scope`		string	`full`		`tabs` (open tabs and session state) or `full` (the whole profile).
`--profile`		string			Chrome profile to capture: a name ("Profile 1") or a path.
`--display-name`		string			Display name for the app (UI only).
`--sandbox`	`-s`	string			Destination sandbox (name).
`--url`		string			Destination cua-spacesd URL instead of a sandbox.
`--token`		string		`CUA_ENV_TOKEN`	Token for `--url`.
`--include`		string			Send exactly this manifest item (repeatable; see `manifest`). Default: the provider's default selection, which leaves credentials-heavy or bulky items (cookies, transcripts) out unless named here.
`--all`		boolean	`false`		Send every item the scope offers.
`--no-launch`		boolean	`false`		Do not launch the app in the sandbox after importing.
`--progress`		boolean	`false`		Print `progress <sent> <total>` lines while uploading.
`--relay-plaintext-ack`		boolean	`false`		Send over a `relay:` destination even though this Space's image predates end-to-end sealing (S1): without this, such a send refuses before reading or uploading anything. Set it only after you understand that relay.cua.ai (or a self-hosted cua-relay) could read this delivery in the clear; local and direct destinations are unaffected either way.

Examples

# Chrome's open tabs into the sandbox dev
cua teleport push --app com.google.Chrome --scope tabs --sandbox dev
 
# The whole Slack profile, every item
cua teleport push --app Slack --sandbox dev --all

`cua keyvault`#

The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals. Passphrases are prompted for (or read from stdin), never arguments.

cua keyvault [OPTIONS] <COMMAND>

Examples

cua keyvault status
cua keyvault init --passphrase
cua keyvault unlock --passphrase
cua keyvault import-passwords --browser chrome
cua keyvault requests
cua keyvault approve <request-id>
cua keyvault lock

`cua keyvault status`#

Whether the Keyvault exists and is unlocked, and which protectors (Touch ID with the OS key store, a passphrase) the daemon can use.

cua keyvault status [OPTIONS]

Examples

cua keyvault status
cua keyvault status --json

`cua keyvault init`#

Create the Keyvault and print its recovery key once. Uses the OS key store (Touch ID confirms) unless --passphrase or --passphrase-stdin.

cua keyvault init [OPTIONS]

Flag	Type	Default	Description
`--passphrase`	boolean	`false`	Use a passphrase, typed at a terminal prompt with echo off.
`--passphrase-stdin`	boolean	`false`	Use a passphrase read from the first line of stdin (scripts).

Examples

# The OS key store (the signed Cua daemon only)
cua keyvault init
 
# A passphrase, typed twice at a prompt
cua keyvault init --passphrase
 
# Scripts: the passphrase is the first line of stdin
cua keyvault init --passphrase-stdin

`cua keyvault unlock`#

Unlock the Keyvault with the OS key store, or with its passphrase.

cua keyvault unlock [OPTIONS]

Flag	Type	Default	Description
`--passphrase`	boolean	`false`	Use a passphrase, typed at a terminal prompt with echo off.
`--passphrase-stdin`	boolean	`false`	Use a passphrase read from the first line of stdin (scripts).

Examples

cua keyvault unlock
cua keyvault unlock --passphrase

`cua keyvault lock`#

Lock the Keyvault (unlocking needs the OS key store or the passphrase again).

cua keyvault lock [OPTIONS]

Examples

cua keyvault lock

`cua keyvault import-passwords`#

Import a browser's saved passwords into the Keyvault, one item per site. They stay sealed: agents sign in with them through request_site_login after you approve, and never see them. The daemon asks for Touch ID or your login password.

cua keyvault import-passwords [OPTIONS]

Flag	Type	Default	Description
`--browser`	`chrome`	`chrome`	The browser to import from.
`--profile`	string		The browser profile (name or path); default: the default profile.
`--site`	string		Only this site (a registrable domain such as github.com). Repeatable; default: every saved site.

Examples

cua keyvault import-passwords --browser chrome
cua keyvault import-passwords --browser chrome --site github.com --site example.com
cua keyvault import-passwords --browser chrome --profile "Profile 1"

`cua keyvault import-session`#

Import a signed-in session (cookies, or a single-app session like Slack's) into the Keyvault, without delivering it anywhere. A later cua teleport push --sandbox NAME (or the review sheet's "Save to Keyvault") can deliver it; it stays sealed until then. The daemon asks for Touch ID or your login password.

cua keyvault import-session [OPTIONS] --app <APP>

Flag	Type	Default	Description
`--app`	string	required	The app to import from (a teleport provider id: `chrome`, `firefox`, `slack`, ...; `cua teleport providers` lists every one on this machine).
`--profile`	string		The browser profile (name or path); default: the default profile. Ignored for a single-app provider (Slack, Discord, ...).
`--site`	string		Only this site's cookies (a registrable domain such as github.com). Repeatable; a browser with none named imports every site's cookies. Ignored (the whole session is one item) for a single-app provider.
`--include-storage`	boolean	`false`	Also carry each named site's localStorage / IndexedDB origins.
`--include-passwords`	boolean	`false`	Also carry each named site's saved passwords, as part of this same session item (`cua keyvault import-passwords` keeps them as their own items instead, one per site).
`--session-only`	boolean	`false`	Only session cookies: drop every persistent cookie.
`--drop-long-lived`	boolean	`false`	Drop persistent cookies that expire more than 30 days out (long-lived refresh tokens), keeping short sessions.

Examples

cua keyvault import-session --app chrome
cua keyvault import-session --app chrome --site github.com --site example.com
cua keyvault import-session --app firefox --profile "Profile 1"
cua keyvault import-session --app slack

`cua keyvault requests`#

Requests waiting for your approval (site logins, teleports).

cua keyvault requests [OPTIONS]

Examples

cua keyvault requests
cua keyvault requests --json

`cua keyvault approve`#

Approve a waiting request (the daemon asks for Touch ID or your login password). A site login is approved for one sign-in.

cua keyvault approve [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required	The request id (`cua keyvault requests`).

Examples

cua keyvault approve 5f2c9a0e

`cua keyvault deny`#

Decline a waiting request.

cua keyvault deny [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required	The request id.

Examples

cua keyvault deny 5f2c9a0e

Exit 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`).
`130`	Cancelled (Ctrl-C during a create): what it made was removed.

Files, teleport and keys

cua volume#

cua volume ls#

cua volume cat#

cua volume put#

cua volume rm#

cua volume history#

cua volume restore#

cua volume grant#

cua volume revoke#

cua volume grants#

cua volume requests#

cua volume approve#

cua volume deny#

cua volume audit#

cua volume mount#

cua volume unmount#

cua volume status#

cua volume config#

cua volume config show#

cua volume config set#

cua volume config set-keys#

cua teleport#

cua teleport providers#

cua teleport manifest#

cua teleport push#

cua keyvault#

cua keyvault status#

cua keyvault init#

cua keyvault unlock#

cua keyvault lock#

cua keyvault import-passwords#

cua keyvault import-session#

cua keyvault requests#

cua keyvault approve#

cua keyvault deny#

Exit codes#

`cua volume`#

`cua volume ls`#

`cua volume cat`#

`cua volume put`#

`cua volume rm`#

`cua volume history`#

`cua volume restore`#

`cua volume grant`#

`cua volume revoke`#

`cua volume grants`#

`cua volume requests`#

`cua volume approve`#

`cua volume deny`#

`cua volume audit`#

`cua volume mount`#

`cua volume unmount`#

`cua volume status`#

`cua volume config`#

`cua volume config show`#

`cua volume config set`#

`cua volume config set-keys`#

`cua teleport`#

`cua teleport providers`#

`cua teleport manifest`#

`cua teleport push`#

`cua keyvault`#

`cua keyvault status`#

`cua keyvault init`#

`cua keyvault unlock`#

`cua keyvault lock`#

`cua keyvault import-passwords`#

`cua keyvault import-session`#

`cua keyvault requests`#

`cua keyvault approve`#

`cua keyvault deny`#