> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```bash theme={null}
# 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
\$ 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\`
\$ 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
\$ 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/\.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