Command Reference

usage: contree [-h] [-v] [-p PROFILE] [—token TOKEN] [-u URL] [-P PROJECT] [-c CONFIG_PATH]
               [-L {debug,info,warning,error,critical}]
               [-f {csv,default,json,json-pretty,plain,table,toml,tsv}] [-S SESSION_KEY]
               {use,ci,run,r,build,bd,images,i,img,tag,t,ps,kill,show,operation,op,ls,cat,cp,file,f,session,s,auth,skill,cd,env,agent,man,shell,sh} …

ConTree CLI - command-line client for the ConTree sandbox platform.

Run sandboxes, manage images, inspect filesystems, and track operations
through the ConTree REST API.

Authentication:
  Bearer token + project ID. Default API URL:
    https://api.tokenfactory.nebius.com/sandboxes/

  Use `contree auth —help` to configure persistent credentials.

Coding-agent bootstrap (important):
  Agents should read `contree agent` before executing task commands.

positional arguments:
  {use,ci,run,r,build,bd,images,i,img,tag,t,ps,kill,show,operation,op,ls,cat,cp,file,f,session,s,auth,skill,cd,env,agent,man,shell,sh}
    use (ci)            Set or show current session image
    run (r)             Spawn a sandbox instance
    build (bd)          Build image from Dockerfile
    images (i, img)     List and import images
    tag (t)             Tag an image
    ps                  List operations (alias for `operation ls`)
    kill                Cancel operations (alias for `operation cancel`)
    show                Show operation result (alias for `operation show`)
    operation (op)      Manage operations (list/show/cancel)
    ls                  List files in image
    cat                 Show file content from image
    cp                  Copy file from image to local path
    file (f)            Manage files in session image
    session (s)         Manage session branches and history
    auth                Configure authentication
    skill               Manage agent skills
    cd                  Change working directory
    env                 Manage session environment variables
    agent (man)         Show manual
    shell (sh)          Interactive shell mode

options:
  -h, —help            show this help message and exit
  -v, —version         show program’s version number and exit
  -p, —profile PROFILE
                        Use this profile for the current command
  —token TOKEN         API token (overrides profile for this invocation)
  -u, —url URL         API base URL (overrides profile for this invocation)
  -P, —project PROJECT
                        Project ID (overrides profile for this invocation)
  -c, —config CONFIG_PATH
                        Config file path (default: /home/runner/.config/contree/auth.ini)
  -L, —log-level {debug,info,warning,error,critical}
                        Logging level (default: info)
  -f, —format {csv,default,json,json-pretty,plain,table,toml,tsv}
                        Output format (default: default)
  -S, —session SESSION_KEY
                        Session key override (alternative to CONTREE_SESSION)

examples:
  contree use tag:ubuntu:latest       set session image
  eval $(contree use tag:ubuntu:latest)  set + export env var
  contree run — uname -a            run command in session image
  contree run —shell — ‘echo hi’   shell mode
  contree run —file ./app.py:/app.py —disposable — python /app.py
  contree run —file ./src:/app/src — make -C /app/src
  contree images —prefix=ubuntu
  contree ps -q
  contree op ls                       same as `contree ps`
  contree op show UUID1 UUID2         multi-UUID show
  contree op cancel UUID1 UUID2       multi-UUID cancel (or —all)
  contree show OPERATION_UUID
  contree tag IMAGE_UUID latest
  contree ls /etc                    list files in session image
  contree cat /etc/os-release        show file from session image
  contree auth                       save token (secure prompt)
  contree auth switch staging
  contree man                        user manual
  contree agent                      coding-agent manual

for users:
  contree man

for coding agents (required bootstrap):
  1) read: contree agent
  2) inspect command syntax: contree <command> —help
  3) only then execute task commands

before running tasks:
  ensure auth exists; if missing/invalid, ask user to run `contree auth`

high-signal read-only commands:
  contree images | ps | show UUID | ls [PATH] | cat PATH | session | session show

mutating commands (change remote or local session state):
  contree use IMAGE | run — CMD | file edit PATH | file cp SRC DEST
  contree tag UUID TAG | kill UUID | cd PATH | session checkout BRANCH

environment variables:
  CONTREE_PROFILE          Active config profile (selects which profile to use)
  CONTREE_SESSION          Explicit session name (for multi-terminal workflows).
                           If unset, contree auto-generates <cwd>+<8hex> (derived
                           from profile+ppid+tty); export your own for stable
                           reuse. You can also pass -S/—session instead.
  CONTREE_SESSION_DB       Path to session SQLite database
  CONTREE_NO_UPDATE_CHECK  Set to any value to disable PyPI update checks

registration-time fallbacks (only read by `contree auth`, not at runtime):
  CONTREE_TOKEN / NEBIUS_API_KEY        Token used when —token is omitted
  CONTREE_URL                           URL used when —url is omitted
  CONTREE_PROJECT / NEBIUS_AI_PROJECT   Project ID used when —project is omitted