> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial

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](https://contree.dev)

## The path

<Columns cols={3}>
  <Card title="1. Install & Authenticate" href="./installation" icon="download">
    Install contree-cli, save your API token, and set up named profiles for
    different environments.
  </Card>

  <Card title="2. Your First Sandbox" href="./first-steps" icon="rocket">
    Browse images, run commands, inspect the filesystem, and download files.
    Understand how each run creates a new checkpoint.
  </Card>

  <Card title="3. Interactive Shell" href="./shell" icon="terminal">
    Use the REPL for rapid iteration: tab completion for paths, images, and
    branches, command aliases, and persistent history.
  </Card>

  <Card title="4. Sessions & Branches" href="./sessions" icon="code-branch">
    Branch off to experiment, roll back mistakes, share sessions across
    terminals, and start fresh when needed.
  </Card>

  <Card title="5. Working with Files" href="./files" icon="folder-open">
    Inject local code into sandboxes, edit remote files in-place, and stage
    changes that auto-attach on the next run.
  </Card>

  <Card title="6. Images & Tags" href="./images" icon="layer-group">
    Tag working images for reuse, import from registries, and search by
    prefix. Build reusable base environments.
  </Card>

  <Card title="7. Building from a Dockerfile" href="./build" icon="hammer">
    Turn a `Dockerfile` into a tagged ConTree image. Layer caching,
    build args, `.dockerignore`, and URL streaming for `ADD`.
  </Card>

  <Card title="8. Scripting & Automation" href="./workflows" icon="gears">
    Shell mode, shebang scripts, detached runs, operation monitoring, and
    machine-readable output formats for pipelines.
  </Card>

  <Card title="9. Configuration & Profiles" href="./configuration" icon="gear">
    Create and switch between profiles for different projects, understand
    how profiles affect sessions, and configure environment variables.
  </Card>
</Columns>

## Quick taste

If you just want to see contree-cli in action before diving in:

<Tabs sync={false}>
  <Tab title="CLI">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={null}
    # install and authenticate first (see CLI tab)
    contree auth

    # start the interactive shell
    contree shell
    ```

    Once inside the shell:

    ```text theme={null}
    contree use tag:ubuntu:latest
    uname -a
    ls /
    cat /etc/os-release
    ```
  </Tab>
</Tabs>

Ready? Start with [Install & Authenticate](./installation).