\$ contree run --help
usage: contree run \[-h] \[-t TIMEOUT] \[-C CWD] \[-e ENV] \[-H HOSTNAME] \[-D] \[-I] \[-s] \[-F FILE]
                   \[--file-excludes PATTERN \[PATTERN ...]] \[-T TRUNCATE] \[--preserve-env] \[-d]
                   \[--use IMAGE]
                   ...

Spawn a sandbox instance from the current session image and execute a command.

Uses the image from the active session (set via \`contree use IMAGE\`),
or an image specified inline via \`\`--use IMAGE\`\`.
Commands are passed after -- separator; without --, the first
positional arg is the command.

By default the CLI polls until the operation reaches a terminal
status (SUCCESS, FAILED, CANCELLED) and prints stdout/stderr.
Use -d/--detach to exit immediately after spawning.

File attachments:
  Use --file to inject host files or directories into the sandbox
  before execution. Files are uploaded to the API (with SHA256 dedup)
  and mounted at the specified instance path. Ownership and
  permissions default to host file stat unless overridden.

  Note: non-disposable runs persist filesystem changes into a
  new image. Files attached once are already part of that image
  and do not need re-attachment. Use --disposable to discard
  changes after execution.

  Format: host\_path\[:instance\_path]\[:uUID]\[:gGID]\[:mMODE]

    host\_path                             all defaults from stat
    host\_path:/inst/path                  point a destination path
    host\_path:m0755                       override only mode
    host\_path:/inst/path:u0:g0:m0755      all explicit
    host\_path:uroot:groot                 uid/gid by name (local)

  Tagged options (u/g/m) can appear in any order after host\_path.
  instance\_path is detected by its leading /.
  For directory attachments, files are walked recursively and default
  excludes are applied: .\*, .git, \*.pyc, \_\_pycache\_\_, .venv,
  .mypy\_cache, .pytest\_cache, node\_modules, dist, build.
  Add extra patterns with --file-excludes.

  The CLI also keeps a local upload cache keyed by
  path+inode+mtime+size and reuses known file UUIDs to avoid
  unnecessary re-upload checks/uploads.

  Note: named uid/gid (e.g. uroot) are resolved locally via
  pwd/grp — use numeric IDs if unsure about host/sandbox mismatch.

positional arguments:
  command\_args          Command and arguments (after --)

options:
  -h, --help            show this help message and exit
  -t, --timeout TIMEOUT
                        Timeout in seconds (default: 120)
  -C, --cwd CWD         Working directory inside sandbox, absolute path or empty string for use
                        sandbox WORKDIR (default: )
  -e, --env ENV         Environment variable KEY=VALUE (repeatable)
  -H, --hostname HOSTNAME
                        Container hostname (default: linuxkit)
  -D, --disposable      Drop filesystem changes after run
  -I, --interpreter     Interpreter (shebang) mode. Read the script file given as the first
                        argument, strip the #! line, and send the body as stdin to /bin/sh -s.
                        Usage: #!/usr/bin/env -S contree run -I
  -s, --shell           Join command args into a single shell expression
  -F, --file FILE       Attach file or directory (repeatable, dirs recurse). Format:
                        host\[:inst\_path]\[:uUID]\[:gGID]\[:mMODE]. Tagged options (u/g/m) in any
                        order; uid/gid resolved locally from pwd/grp; defaults from host stat.
  --file-excludes PATTERN \[PATTERN ...]
                        Additional glob exclude patterns for directory attachments (repeatable).
  -T, --truncate TRUNCATE
                        Truncate output to N bytes (default: 65536)
  --preserve-env        Preserve env vars from previous run (server-side)
  -d, --detach, --no-wait
                        Exit immediately after spawning (do not wait for result)
  --use IMAGE           Switch session to IMAGE before running (UUID or tag:NAME). Equivalent to
                        'contree use IMAGE' followed by 'run'. Recorded in session history and can
                        be rolled back with 'session rollback'. (default: )

examples:
  contree use ubuntu && contree run -- uname -a
  contree run --use tag:ubuntu:latest -- uname -a
  contree run --shell -- 'echo hello && ls /'
  contree run -e FOO=bar DEBUG=1 -- ./app
  contree run --file ./app.py:/app.py --disposable -- python /app.py
  contree run --file ./src:/app/src --file-excludes '\*.log' -- make -C /app/src
  contree run -d -- sleep 3600

for coding agents:
  \`run\` executes remotely inside the instance image (not on local host)
  local files/dirs must be mapped with --file to be available remotely
  mutates session image unless --disposable is set
  supports directory attachments via --file host\_dir:/instance\_dir
  local file cache avoids re-upload when path+inode+mtime+size unchanged
  returns command exit code when available
  default formatter prints raw stdout/stderr only
  use -f json for structured operation metadata

agent note:
  Before using this command in an automated workflow, read:
    contree agent