Commands and files

Run shell commands and move files in and out of a Space.

Tool	Description
`space_bash`	Run a shell command inside the Space.
`space_write`	Write literal text to a path inside the Space.
`upload`	Send a local file or folder into the Space.
`send_file`	Send a host file or folder into the Space's Downloads, verified by sha256 on arrival.
`download`	Fetch a file or folder out of the Space.

space_bash#

Run a shell command inside the Space.

Runs through the spacesd's ProcessService with /bin/sh -c. Output is stdout, then [stderr] and stderr, then [exit N]; each stream keeps its last 16000 characters when longer.


Providers	all (cloud, local, direct, relay)
Platforms	all (macos, windows, linux)
Metering	free
Approval	permission `spaces:space_bash`; destructive
Swift SDK	`Space.bash(_:)`
Rust	`Space::bash`

Parameters#

Parameter	Type	Default	Description
`command`	`string`	required	Command line, run with `/bin/sh -c` (`cmd.exe /C` on Windows guests).
`space`	`string`	required	Space id or name.
`timeout`	`integer`	`60`	Seconds before the command is killed. Default 60. At least 0.

Result#

Text: stdout, then [stderr] and stderr, then [exit N].

Errors#

invalid_argument, not_found, ambiguous_sandbox, timeout

space_write#

Write literal text to a path inside the Space.

Written through FilesystemService, verified by sha256; no shell is involved, so nothing needs quoting.


Providers	all (cloud, local, direct, relay)
Platforms	all (macos, windows, linux)
Metering	free
Approval	permission `spaces:space_write`; destructive
Swift SDK	`Space.write(_:to:)`
Rust	`Space::write`

Parameters#

Parameter	Type	Default	Description
`content`	`string`	required	The exact file contents.
`path`	`string`	required	Absolute path in the Space. Parent directories are created.
`space`	`string`	required	Space id or name.

Result#

Text: wrote <path> (<n> bytes, sha256 <hex> verified in Space).

Errors#

invalid_argument, not_found, ambiguous_sandbox, transfer_failed

Notes#

Literal text: no local file is read and nothing is shell-quoted, which is the whole reason it exists next to space_bash.

upload#

Send a local file or folder into the Space.

Files stream through FilesystemService in chunks with a sha256 check; a folder is copied file by file (empty directories included, symlinks skipped). No size cap.


Providers	all (cloud, local, direct, relay)
Platforms	all (macos, windows, linux)
Metering	free
Approval	permission `spaces:upload`; destructive
Swift SDK	`space.files.send(_:to:within:)`
Rust	`Space::upload`

Parameters#

Parameter	Type	Default	Description
`dest`	`string`	`<guest home>/<name>`	Absolute destination path in the Space; an existing file there is replaced. Default: `<guest home>/<name>`, or `<name> (1).ext` when that is taken (nothing is replaced).
`path`	`string`	required	Host path (file or folder).
`space`	`string`	required	Space id or name.

Result#

JSON: source, dest, kind (file or folder), files, directories, bytes, sha256 (single file) and verified.

Errors#

invalid_argument, not_found, ambiguous_sandbox, transfer_failed, io

Notes#

Without dest nothing in the Space is replaced: a taken <home>/<name> lands as <name> (1).ext. An explicit dest is written as given and replaces a file already there.

send_file#

Send a host file or folder into the Space's Downloads, verified by sha256 on arrival.

The same transfer the Cua Spaces pop-out's Teleport drop zone performs: files land in the Space user's ~/Downloads through the spacesd's TeleportService (chunked, resumable, every file verified by sha256 before it is published). A transfer that does not land, or lands corrupted, is an error and not a reported success.

respect_ignorefiles (default true) applies ONLY when path is a folder. It honors .gitignore and .ignore at the folder root and in every subdirectory (each scoped to its own subtree, so a nested ignore file overrides its parent), plus .dockerignore at the root only. All three use gitignore semantics: negation (!), directory-only patterns (foo/), anchoring, */?/[...], **, comments, last-matching-rule-wins. As in git, an excluded directory is pruned and ! cannot re-include anything beneath it. .git/ is always skipped and symlinks are never followed. For a single named file it has NO effect.


Providers	all (cloud, local, direct, relay)
Platforms	all (macos, windows, linux)
Metering	free
Approval	permission `spaces:send_file`; destructive
Swift SDK	`Space.sendFile(_:into:respectingIgnoreFiles:)`
Rust	`Space::send_file`

Parameters#

Parameter	Type	Default	Description
`path`	`string`	required	Host path (file or folder) to send.
`respect_ignorefiles`	`boolean`	`true`	Honor `.gitignore` / `.ignore` (nested) and `.dockerignore` (root only) when sending a folder. Default true. No effect on a single named file.
`space`	`string`	required	Space id or name.
`target_directory`	`string`	`~/Downloads`	Subdirectory of the Space user's `~/Downloads` to land in. `~/Downloads` and `~/Downloads/<sub>` are accepted too. Default: `~/Downloads` itself.

Result#

JSON: source, destination, dest, kind, files (each path, size, sha256), bytes, respect_ignorefiles, skipped_by_ignorefiles, skipped_count, skipped_by_guest and verified.

Errors#

invalid_argument, not_found, ambiguous_sandbox, transfer_failed, io

Notes#

Unlike upload, the copy is verified in the Space by sha256 before the call returns: a transfer that does not land, or lands corrupted, is an error and not a reported success.
respect_ignorefiles applies only when the path is a folder, with gitignore semantics; a file named explicitly is always sent.
A file of the same name already in the Space is kept: the new copy lands as name (1).ext and its path is in files.

download#

Fetch a file or folder out of the Space.

Files stream through FilesystemService and are verified by sha256; a folder is copied recursively.


Providers	all (cloud, local, direct, relay)
Platforms	all (macos, windows, linux)
Metering	free
Approval	permission `spaces:download`, in `spaces:readonly`; read-only, idempotent
Swift SDK	`Space.download(_:into:)`
Rust	`Space::download`

Parameters#

Parameter	Type	Default	Description
`dest`	`string`	`~/Downloads/cua-spaces`	Host destination directory. Default `~/Downloads/cua-spaces`.
`path`	`string`	required	Absolute path in the Space (file or folder).
`space`	`string`	required	Space id or name.

Result#

JSON: source, dest, kind, files, bytes, sha256 (single file) and verified.

Errors#

invalid_argument, not_found, ambiguous_sandbox, transfer_failed, io

Notes#

Nothing on the host is overwritten: when dest already has an entry of that name the copy lands as name (1).ext (or name (1) for a folder), and dest in the result is the path used.