Move and Read Files

Work in a box starts with files going in and ends with results coming out. box cp moves files and directories between your machine and a box. When you only want to look at something, such as a log, a report, or a built page, you can read it directly without a transfer and without waking the box.

Send a project into a box

Make one small local directory, then upload it:

⌘Copymkdir -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.

Bring results back

Create one file inside the box, then download it:

⌘Copysys9 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:

⌘Copybox-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.

By default box cp confirms the transfer with one OK: line. Use JSON for a scriptable summary:

⌘Copysys9 run --json box cp ./project work:/work/

Look at files without copying them

To check one file or list a directory, read it in place. The same commands work for boxes and snaps:

⌘Copysys9 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.

Open a file or a built page by link

To show a test report or a built site to someone, or to let another program fetch a file, use the Files link that box inspect and snap inspect print. Add a path to it:

⌘Copycurl <files-link>work/site/index.html
curl '<files-link>work/site/?list=1'

• The link is read-only and does not wake a stopped box.
• An HTML page opened this way loads the images, scripts, and styles it references with relative paths, so a built site or a test report can be viewed in place.
• A directory is listed only with ?list=1; there is no automatic index page.
• Range requests work, so large files can be read in parts.

Anyone who has the link can read those files without logging in. Treat it like a password. The link of a box stops working when the box is removed.