Tutorial

Learn contree-cli by building a real workflow — from zero to automated scripting in six 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.

Install & Authenticate
2. Your First Sandbox

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

Your First Sandbox
3. Interactive Shell

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

Interactive Shell
4. Sessions & Branches

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

Sessions, Branches & Rollback
5. Working with Files

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

Working with Files
6. Images & Tags

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

Images & Tags
7. Scripting & Automation

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

Scripting & Automation
8. Configuration & Profiles

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

Configuration & Profiles

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

# install and authenticate first (see CLI tab)
contree auth

# start the interactive shell
contree shell

Once inside the shell:

contree use tag:ubuntu:latest
uname -a
ls /
cat /etc/os-release

Ready? Start with Install & Authenticate.