cua volume
Cua Volume: files, versions, grants, access requests and audit of the volume every Space and agent shares.
Cua Volume: files, versions, grants, access requests and audit of the volume every Space and agent shares.
| Command | Description |
|---|---|
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, cloud). |
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. |
Every command also accepts the global options.
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 auditcua 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:workcua 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 | Default | 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-1a2b3c4dcua 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-onlycua volume rm#Delete a file (its history stays).
cua volume rm [OPTIONS] <PATH>| Argument | Type | Default | Description |
|---|---|---|---|
<PATH> | string | required |
| Flag | Type | Default | 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.txtcua 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.mdcua 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-1a2b3c4dcua 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 2hcua volume revoke#Revoke a grant.
cua volume revoke [OPTIONS] <GRANT_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<GRANT_ID> | string | required |
Examples
cua volume revoke 5f2c9a0b1d3e4f67cua 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 grantscua volume requests#Access requests agents filed, waiting for you.
cua volume requests [OPTIONS]Examples
cua volume requestscua 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 1dcua volume deny#Decline a request.
cua volume deny [OPTIONS] <REQUEST_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<REQUEST_ID> | string | required |
Examples
cua volume deny 5f2c9a0b1d3e4f67cua 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 --jsoncua 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 --jsoncua volume unmount#Turn the volume off (files still uploading land first).
cua volume unmount [OPTIONS]Examples
cua volume unmountcua volume status#The volume, sync across devices, and the block cache.
cua volume status [OPTIONS]Examples
cua volume status
cua volume status --jsoncua volume config#Which store the drive uses (fs, s3, cloud).
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 showcua 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), s3, or cloud (off unless the Cua cloud enables it). |
--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-stylecua 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| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure, or cua do reported an error. |
2 | Invalid argument, or an ambiguous sandbox name (qualify it: local:NAME, cloud:NAME). |
3 | Not found: sandbox, window, skill or image (or an image not published yet). |
4 | Not supported, or not configured (for example no Fleet credentials). |
5 | No cua-spacesd answered, or a transport failure. |
6 | Unauthenticated or permission denied (by Cua, Fleet 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. |