Skip to main content
Stage file changes for the next contree run. Pending files are automatically included without needing --file flags.

​
Examples

​
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 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.
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 —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 -o 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