contree-cli 0.2.3

ConTree simple CLI

contree-cli

Command-line client for the ConTree sandboxing platform — secure, VM-isolated sandboxes with git-like branching for AI agents and developers.

eval $(contree use tag:ubuntu:latest)   # pick a base image for current session
contree run apt-get update -qq          # each run snapshots the result
contree run apt-get install -y curl     # builds on the previous snapshot
contree session branch experiment       # branch the sandbox state
contree run -- make test                # experiment freely
contree session checkout main           # switch back instantly
contree session rollback 2              # or rewind two steps

What is ConTree?

ConTree is a secure sandbox API that runs every command inside a VM-isolated instance and snapshots the full filesystem after each execution. These snapshots (called images) form a tree — branch from any checkpoint, explore paths in parallel, and roll back on failure.

Built for AI agents that think ahead:

• Tree-search execution — branch sandbox state so an agent can explore multiple solution paths in parallel and keep the best one
• Instant rollback — backtrack to any previous checkpoint without rebuilding from scratch
• Safe code execution — run untrusted or LLM-generated code inside VM-level isolation; crashes and side effects stay in the sandbox
• Session continuity — rewind and resume long-running agent workflows with full filesystem context preserved

contree-cli talks to the ConTree API. Install it, authenticate with your project token, and create sandboxes, run commands, inspect filesystems, and manage sessions — all from your terminal, shell scripts, or agent toolchains.

Install

pip install contree-cli

Or with uv:

uv tool install contree-cli

More options (pipx, from source)

# pipx
pipx install contree-cli

# From source
git clone https://github.com/nebius/contree-cli.git
cd contree-cli
pip install .

Verify:

contree --help

Requirements: Python 3.10+ and nothing else. Zero external dependencies — stdlib only.

Quick Start

1. Authenticate

contree auth

You'll be prompted to enter your API token securely. The CLI verifies it and saves it to ~/.config/contree-cli/config.ini.

2. Start a session

eval $(contree use tag:ubuntu:latest)

This picks a base image and creates a session. The eval wrapper exports the session variable so subsequent commands share the same state.

3. Run commands

contree run uname -a                  # direct execution
contree run apt-get install -y curl   # installs persist to next run
contree run -s -- 'echo $PATH'        # shell mode for expansions

Each non-disposable run produces a new image — a full filesystem checkpoint.

4. Inspect without spawning

contree ls /usr/bin          # list files (no VM needed)
contree cat /etc/os-release  # read files (no VM needed)
contree cp /app/output.log . # download to local machine

5. Branch and roll back

contree session branch experiment     # create a branch
contree run -- make test              # experiment on it
contree session checkout main         # switch back
contree session rollback 1            # undo last run

Interactive Shell

contree shell starts a REPL where bare commands run in the sandbox automatically:

$ contree shell
contree:/> apt-get update -qq
...
contree:/> apt-get install -y curl
...
contree:/> curl -sI https://example.com
HTTP/2 200
...
contree:/> cd /etc
contree:/etc> cat os-release
PRETTY_NAME="Ubuntu 24.04 LTS"
...
contree:/etc> contree session branch experiment
Created branch 'experiment'
contree:/etc> exit

The shell provides tab completion for commands, paths, image tags, and operation IDs. ls and cat map to the fast API inspection commands by default. vim/vi/nano open contree file edit with your local $EDITOR.

Commands

Command	Aliases	Description
use IMAGE	ci	Set or show current session image
run [-- CMD]		Spawn a sandbox instance, execute command
images [--prefix]	img	List available images
tag UUID TAG		Tag or untag an image
ps		List operations (instances, imports)
kill UUID		Cancel an operation (--all for all)
show UUID		Show operation result
ls [PATH]		List files in session image (no VM)
cat PATH		Show file content from session image (no VM)
cp PATH DEST		Download file from image to local path
file edit PATH	e	Edit remote file via local $EDITOR
file cp SRC DEST		Upload local file into session image
cd [PATH]		Change working directory in session
session	s	Show current session info
session list	ls	List all sessions
session branch	br	Create or list branches
session checkout	co	Switch active branch
session rollback [N]	rb	Revert N steps in history
session show		Display session history DAG
auth		Configure authentication (secure prompt)
auth profiles		List saved profiles
auth switch NAME		Switch active profile
shell		Start interactive REPL

See the full command reference for all flags and options.

Execution Modes

The run command supports four execution modes:

# Direct — arguments are the command
contree run uname -a

# Shell — arguments joined, passed to sh -c
contree run -s -- 'echo $HOME && ls /'

# Interpreter — local script executed remotely
contree run -I ./deploy.sh

# Piped stdin — stdin forwarded to the command
echo 'SELECT 1' | contree run -- psql

File injection

Mount local files into the sandbox:

contree run --file ./app.py:/app/app.py -- python /app/app.py
contree run --file ./config.yaml --file ./data.csv -- ./process.sh

File specs support permissions: host_path[:remote_path][:uUID][:gGID][:mMODE]

Shebang scripts

#!/usr/bin/env -S contree run -I
apt-get update -qq
apt-get install -y curl
curl https://example.com

Save as setup.sh, chmod +x, and run it directly.

Sessions and Branching

Sessions track your sandbox state with git-like branching and history:

main:  A ── B ── C ── D
                  \
experiment:        E ── F

Every run creates a checkpoint. Branch to explore alternatives. Roll back to any point. Switch branches instantly.

contree session                       # show current state
contree session show                  # display history DAG
contree session branch feature        # create branch from HEAD
contree session checkout feature      # switch to it
contree session rollback 3            # go back 3 steps
contree session use other-session     # import image from another session

Output Formats

All commands support structured output via -f/--format:

contree images -f json                # JSON (one object per line)
contree images -f json-pretty         # pretty-printed JSON array
contree ps -f csv                     # RFC 4180 CSV
contree ps -f tsv                     # tab-separated values
contree ls -f table                   # ASCII table

Pipe JSON output into jq, feed CSV into spreadsheets, or parse programmatically in your agent toolchain.

Configuration

Config file

~/.config/contree-cli/config.ini:

[DEFAULT]
profile = default

[profile:default]
token = eyJ...
url = https://contree.dev

Multiple profiles

contree auth --profile=staging        # save staging token
contree auth --profile=prod           # save production token
contree auth profiles                 # list all profiles
contree auth switch staging           # switch active profile

Environment variables

Variable	Purpose
CONTREE_TOKEN	API bearer token (overrides config)
CONTREE_URL	API base URL (overrides config)
CONTREE_PROFILE	Active profile name
CONTREE_SESSION	Explicit session key (for multi-terminal workflows)
CONTREE_SESSION_DB	Path to session SQLite database

Environment variables take precedence over the config file. --token and --url flags override everything.

Zero Dependencies

contree-cli uses only the Python standard library. No requests, no click, no rich — just http.client, argparse, json, sqlite3, and friends. It runs anywhere Python 3.10+ is available with nothing to install beyond the package itself.

Development

git clone https://github.com/nebius/contree-cli.git
cd contree-cli
uv sync --group dev

make lint       # ruff check --fix
make types      # mypy strict mode
make check      # lint + types
make tests      # lint + types + pytest

The project enforces strict mypy, ruff linting (E/F/W/I/UP/B/SIM/RUF rules), and full test coverage across 23+ test modules.

Documentation

Full documentation is available at docs.contree.dev/cli, including:

• Tutorial — step-by-step from installation to automation
• Command Reference — every command, flag, and subcommand

Links

• ConTree Platform
• Documentation
• PyPI
• Issues
• Releases