Copy files

tektona sandbox cp copies files between your local filesystem and a sandbox over the brokered SSH/SFTP path, the same one tektona ssh uses. No public IP, no key management, no manual scp.

Behaviour mirrors POSIX cp: single-file sources copy to a file or into an existing directory, recursive transfers copy whole trees, multiple sources require an existing-directory destination.

Sandbox refs

A ref names either a local path or a path inside a specific sandbox:

All sources in a single invocation must be on the same side: all local, or all from the same sandbox. Mixing is rejected before any SSH dial.

Upload a single file

tektona sandbox cp ./report.pdf 01JQXYZ123ABCDEFGHJKMNPQRS:/tmp/

If the destination ends in / (or is an existing directory), the file is written as /tmp/report.pdf. Without a trailing slash and pointing at a non-existent path, the file is written under that exact name.

Use the working-directory shorthand

The bare <ULID>: form — or just <ULID> with no colon at all — drops the file into the same directory tektona ssh would land in:

tektona sandbox cp ./report.pdf 01JQXYZ123ABCDEFGHJKMNPQRS

For a sandbox built from an image with WORKDIR /home/tektona, the upload lands at /home/tektona/report.pdf. Relative remote paths (<ULID>:reports/q1.pdf) resolve the same way. When the image doesn't set WORKDIR, the destination falls back to $HOME, matching what an ssh session would land in.

Download a single file

tektona sandbox cp 01JQXYZ123ABCDEFGHJKMNPQRS:/var/log/app.log ./

Same rules in reverse: trailing-slash or existing-directory destination copies in, and a non-existent destination renames to that name.

Copy a directory tree

-r (or --recursive) recurses into directories:

# upload a tree
tektona sandbox cp -r ./build/ 01JQXYZ123ABCDEFGHJKMNPQRS:/srv/app/

# download a tree
tektona sandbox cp -r 01JQXYZ123ABCDEFGHJKMNPQRS:/var/log/myapp ./logs/

Symlinks are preserved as symlinks by default. Pass -L (--follow-links) to follow them and copy the targets instead.

Multiple sources

When you pass more than one source the destination must be an existing directory:

tektona sandbox cp file1.txt file2.txt logs/ 01JQXYZ123ABCDEFGHJKMNPQRS:/inbox/

Parallel transfers

Bulk transfers run across a worker pool of independent SFTP sessions. Tune with --workers:

tektona sandbox cp --workers=6 -r ./large-dataset/ 01JQXYZ123ABCDEFGHJKMNPQRS:/data/

Default is 3, hard-capped at 6. Adding more workers past that point gives little throughput gain, so values higher than 6 are clamped with a warning.

Directories and symlinks are always created sequentially before any file upload starts, so files always find their parent directory.

Preserve mode and mtime

tektona sandbox cp -p ./script.sh 01JQXYZ123ABCDEFGHJKMNPQRS:/usr/local/bin/

-p (--preserve) keeps the executable bit, mode and modification time on the destination.

Stream from stdin or to stdout

- reads from stdin or writes to stdout depending on which side it appears:

# pipe content into a remote file
tar c ./src | tektona sandbox cp - 01JQXYZ123ABCDEFGHJKMNPQRS:/tmp/src.tar

# stream a remote file through a local pipeline
tektona sandbox cp 01JQXYZ123ABCDEFGHJKMNPQRS:/var/log/app.log - | grep ERROR

-r is incompatible with -, and --output json is incompatible with - as the destination.

Fail fast on the first error

By default a per-file error is reported and the remaining files continue. Pass --fail-fast to abort the run on the first error:

tektona sandbox cp -r ./build/ 01JQXYZ123ABCDEFGHJKMNPQRS:/srv/app/ --fail-fast

JSON output for scripts

tektona sandbox cp --output json -r ./build/ 01JQXYZ123ABCDEFGHJKMNPQRS:/srv/app/

Emits a stream of typed events (WalkStarted, WalkComplete, FileStarted, FileProgress, FileDone, DirCreated, SymlinkCreated, TransportLost, Done), one JSON object per line.

Exit codes

Limitations

• Resumable transfers are not implemented. A transport drop fails the run with exit code 2 and you re-issue the command.
• Sandbox refs require a full 26-character ULID. ID prefixes (01JQ:) are rejected to avoid ambiguity.