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/](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 \ --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 \+\<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