Copy files

Move files between your machine and a sandbox over SFTP with POSIX-cp semantics.

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:

FormMeaning
path/to/fileA local path.
-stdin (as source) or stdout (as destination).
<ULID>:/abs/pathInside the sandbox with id <ULID> (a full 26-character ULID, prefixes are rejected).
<ULID>:rel/pathResolves against the sandbox's working directory (the image's WORKDIR, falling back to $HOME). Same directory tektona ssh lands in.
<ULID>: or <ULID>Shorthand for <ULID>:., the working directory itself. The trailing colon is optional. Uploads land there with the source basename.

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.

A download writes only inside the local destination. If a path in the destination is a local symlink that points outside it, that entry fails and the rest of the copy continues.

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

CodeMeaning
0All transfers succeeded.
1One or more per-file errors (run otherwise completed).
2Transport failure: the SSH/SFTP session dropped mid-run.
130Interrupted by the user (Ctrl-C).

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.

On this page