TUTORIAL

Files and Transfer

Browse, read, and move box or snap files without turning file access into a shell script exercise.

Use the read-only file commands to browse or stream individual files. Use box cp when you need to upload a directory or transfer an archive.

Browse and read files

The same command shape works for boxes and snaps:

sys9 run box file ls work /work/site
sys9 run box file stat work /work/site/index.html
sys9 run box file cat work /work/site/index.html
sys9 run box file get work /work/site/index.html ./index.html

sys9 run snap file ls <snap-id> /work/site
sys9 run snap file cat <snap-id> /work/site/index.html

An online box reads its current mounted filesystem. A stopped box reads its latest settled state. A detached snap always reads its immutable settled state. These commands do not start a transfer job or wake a stopped box.

file ls is paginated with --limit and --cursor. file cat writes raw bytes to stdout and supports --range bytes=0-1023; it intentionally rejects JSON output. file stat, file ls, and file get support the normal text and JSON output modes.

Local to box

Make one small local directory, then upload it:

mkdir -p ./project
printf 'hello from run9\n' > ./project/README.md
sys9 run box create work
sys9 run box exec work mkdir -p /work
sys9 run box cp ./project work:/work/
sys9 run box exec work ls -la /work/project

After the last command, the box contains /work/project/README.md.

Box to local

Create one file inside the box, then download it:

sys9 run box exec work mkdir -p /work/out
printf 'report from run9\n' | sys9 run box exec work -i tee /work/out/report.txt >/dev/null
sys9 run box cp work:/work/out/report.txt ./report.txt

Now ./report.txt is back on your machine.

How box paths work

box cp moves data between your machine and one box, so one side stays local and the other uses a box path:

box-id:/absolute/path

Local-to-local and box-to-box copies are separate workflows. When copying a local directory, end the target with / so the directory name is kept under that target. Create the destination directory first when you want the upload to land inside an existing place.

Output

Default output confirms the transfer:

OK: Copied ./project to work:/work/project.

Use JSON for a scriptable transfer summary:

sys9 run --json box cp ./project work:/work/