> ## 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.

# CLI quickstart

> Install the Sandboxes CLI, configure a profile, and reuse saved filesystem state.

The CLI keeps a local session pointed at an image. This quickstart uses `contree-cli` 0.9.4 and `ubuntu:latest` to save a file in one operation and read it in the next.

<Steps>
  <Step title="Install and authenticate">
    <span id="1-install-and-authenticate" />

    Create an API key and copy the project ID as described in [Set up access](/sandboxes/start/set-up-access#create-an-api-key-and-find-the-project-id), then install CLI 0.9.4:

    ```bash theme={null}
    uv tool install "contree-cli==0.9.4"
    contree --version
    contree auth
    contree auth ls
    ```

    `contree auth` prompts for the API key without echoing it, then for the project ID, and saves a local profile. Values supplied through flags or environment variables skip the corresponding prompt. `contree auth ls` probes the profile. Continue when its status is `ok`.

    For non-interactive profile registration, set the CLI-specific project variable before running `auth`:

    ```bash theme={null}
    export NEBIUS_API_KEY="YOUR_API_KEY"
    export NEBIUS_AI_PROJECT="YOUR_PROJECT_ID"
    contree auth -y
    ```

    The CLI reads these values when registering the profile. Later CLI commands use the saved profile.
  </Step>

  <Step title="Find and select an image">
    <span id="2-find-and-select-an-image" />

    List available Ubuntu images and note the immutable UUID in the first column:

    ```bash theme={null}
    contree images --prefix=ubuntu
    ```

    Select `ubuntu:latest` in a unique local session:

    ```bash theme={null}
    export CONTREE_SESSION="quickstart-$USER-$$"
    contree use tag:ubuntu:latest
    ```

    A tag is convenient for discovery, but it can move. Record the resolved image UUID when reproducibility matters.
  </Step>

  <Step title="Save and reuse a file">
    <span id="3-save-and-reuse-a-file" />

    CLI runs retain changes and advance the session unless `-D` or `--disposable` is present. Choose the retained mode by omitting that flag before submitting the first command:

    ```bash theme={null}
    # No -D: retain the resulting filesystem and advance the session image.
    contree run -- sh -c 'printf "ready\n" > /tmp/quickstart.txt'
    contree run -D -- cat /tmp/quickstart.txt
    ```

    Expected output from the second command:

    ```text theme={null}
    ready
    ```

    Each command starts fresh compute. The session carries the selected image, working directory, staged files, and history; it does not keep the previous VM or process running.
  </Step>

  <Step title="Verify disposable behavior">
    <span id="4-verify-disposable-behavior" />

    Use `-D` for a command whose filesystem changes must not advance the session:

    ```bash theme={null}
    contree run -D -- sh -c 'printf "temporary\n" > /tmp/disposable.txt'
    contree run -D -- test ! -e /tmp/disposable.txt
    ```

    The second command exits successfully because the previous disposable run did not change the session image.
  </Step>
</Steps>

## Continue

* [Sessions and execution modes](/sandboxes/concepts/sessions-and-execution-modes)
* [CLI tutorial](/sandboxes/cli/tutorial/index)
* [CLI command reference](/sandboxes/cli/commands/index)
* [Troubleshooting](/sandboxes/operate/troubleshooting)