Skip to main content
Learn contree-cli by building a real workflow – from zero to automated scripting in nine short sections.

​
What you’ll build

By the end of this tutorial you will:
  • Spin up sandboxes from images and run arbitrary commands
  • Track sandbox state through sessions with branching and rollback
  • Inject local files, edit remote configs, and tag working images
  • Script everything with JSON output, detached runs, and operation monitoring

​
Before you start

You need two things:
  • Python 3.10+ installed on your machine
  • A ConTree API token — get one from your project dashboard

​
The path

1. Install & Authenticate

Install contree-cli, save your API token, and set up named profiles for different environments.

2. Your First Sandbox

Browse images, run commands, inspect the filesystem, and download files. Understand how each run creates a new checkpoint.

3. Interactive Shell

Use the REPL for rapid iteration: tab completion for paths, images, and branches, command aliases, and persistent history.

4. Sessions & Branches

Branch off to experiment, roll back mistakes, share sessions across terminals, and start fresh when needed.

5. Working with Files

Inject local code into sandboxes, edit remote files in-place, and stage changes that auto-attach on the next run.

6. Images & Tags

Tag working images for reuse, import from registries, and search by prefix. Build reusable base environments.

7. Building from a Dockerfile

Turn a Dockerfile into a tagged ConTree image. Layer caching, build args, .dockerignore, and URL streaming for ADD.

8. Scripting & Automation

Shell mode, shebang scripts, detached runs, operation monitoring, and machine-readable output formats for pipelines.

9. Configuration & Profiles

Create and switch between profiles for different projects, understand how profiles affect sessions, and configure environment variables.

​
Quick taste

If you just want to see contree-cli in action before diving in: 
# install
git clone https://github.com/nebius/contree-cli.git
cd contree-cli && uv sync

# authenticate (token prompted securely)
contree auth

# start a session and run a command
eval $(contree use tag:ubuntu:latest)
contree run uname -a

# inspect the result
contree ls /
contree cat /etc/os-release
Ready? Start with Install & Authenticate.