file - Stage file edits for the next run

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

$ contree file --help 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                         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.

$ contree file cp --help 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.

Important

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 != "")'
$ contree file ls --help 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