Stage file changes for the next contree run. Pending files are
automatically included without needing --file flags.
Examples
# Edit a file from the image in $EDITOR
contree file edit /etc/nginx/nginx.conf
# Stage a local file at a specific path
contree file cp ./config.yaml /etc/app/config.yaml
# Both edits apply on the next run
contree run nginx -t
Help output
usage: contree file [-h] {edit,e,cp,ls,list} …
Manage files in the session image.
Subcommands:
edit (e) Download a file from the session image, open it in $EDITOR
(or vi), and upload the modified version as a pending file
attachment. The change takes effect on the next `run`.
cp Copy a local file into the session image as a pending file
attachment. The file is uploaded immediately but injected
into the sandbox on the next `run`.
Pending files are branch-aware — switching branches changes which
files are visible.
positional arguments:
{edit,e,cp,ls,list}
edit (e) Edit a file in the session image
cp Copy a local file into the session image
ls (list) List uploaded files (joined with local cache)
options:
-h, —help show this help message and exit
for coding agents:
mutating command (stages pending file changes for next run)
file edit PATH uses local editor and uploads on change
file cp SRC DEST uploads local file and stages DEST path
agent note:
Before using this command in an automated workflow, read:
contree agent
Subcommands
file edit
contree file edit PATH (alias e) downloads the file at PATH from
the session image, opens it in $EDITOR (defaults to vi), and stages
the modified buffer as a pending upload that will be injected into the
next contree run. Missing files are created as empty buffers so the
command doubles as touch + open.
$ contree file edit —help
usage: contree file edit [-h] [-E EDITOR] path
Edit a remote file via a local editor. The updated content is uploaded and staged as a pending
file for the next run.
positional arguments:
path Path inside image
options:
-h, —help show this help message and exit
-E, —editor EDITOR Editor command (default: /usr/bin/vim)
for coding agents: mutates session state (adds pending file entry) does not apply immediately;
effect appears on next `contree run`
file cp
contree file cp SRC DEST (alias f) reads a local file at SRC, uploads
it to the project’s file store, and stages it for delivery at DEST inside
the session image on the next contree run. Use this when you have a file
ready on disk locally and just want it materialised inside the sandbox
without spawning an instance first.
usage: contree file cp [-h] src dest
Upload a local file and stage it as a pending attachment to be injected on the next run.
positional arguments:
src Local file path
dest Destination path inside image
options:
-h, —help show this help message and exit
for coding agents: mutates session state (adds pending file entry) destination path is inside
sandbox filesystem
file ls
contree file ls lists files uploaded to the project (GET /v1/files)
and joins each row with the local upload cache. The SOURCE column shows
whatever this machine produced the file from:
- absolute host path for files uploaded via
run --file or COPY;
https://... URL for files fetched via ADD URL.
SOURCE resolves only for files uploaded from this very machine.
The mapping lives in the local SQLite cache (per-profile, under
$CONTREE_HOME/cli/sessions/<profile>.db) keyed by
path + inode + mtime + size (host paths) or by the URL itself (URL
fetches). It is not synced anywhere, so a row will show an empty
SOURCE whenever:
- the file was uploaded by a different machine, container, or teammate;
- the file was uploaded by an earlier CLI version that did not yet
track its origin (those entries backfill the next time the file is
matched by the local cache);
- the host file has been moved, renamed, or its
inode/mtime/size has
changed since upload (the cache key no longer matches and the
mapping is treated as missing until the next upload).
There is no way to recover the source of a file uploaded from another
machine – the server stores only uuid, sha256, size,
created_at, and updated_at.contree file ls
contree file ls --since 1d --limit 200
contree file ls -q # uuid + sha256 + source only
contree -f json file ls | jq 'select(.source != "")'
usage: contree file ls [-h] [—since SINCE] [—until UNTIL] [—limit LIMIT] [-q]
List remote files uploaded to the project and, when present in the local upload cache, show what
produced them under the ‘source’ column: either an absolute host path (for run —file / COPY
uploads) or a URL (for ADD URL). source is THIS-MACHINE ONLY: the mapping lives in the local CLI
cache ($CONTREE_HOME/cli/sessions/<profile>.db) and is never synced. Files uploaded from a
different host, by a teammate, or before tracking landed will show an empty source — that is
expected, not a bug. Use the remote uuid or sha256 for cross-machine identity.
options:
-h, —help show this help message and exit
—since SINCE Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.
—until UNTIL Show files before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date to
UTC datetime.
—limit LIMIT Stop after this many files and warn if more are available
-q, —quiet Emit only uuid, sha256, and source columns. source is populated only for files
uploaded from this very machine.
examples: contree file ls contree file ls —since 1d contree file ls —limit 5000 contree file ls
-q # uuid + sha256 + source contree -f json file ls
Pending files
Pending files accumulate until the next contree run consumes them.
Explicit --file flags on contree run take priority over pending files
at the same path.
Files are uploaded with SHA256 dedup – identical content is not re-uploaded.
See also
