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

# session - Manage sessions, branches, history

Manage session branches and history. Sessions track the image state as you
run commands, with support for branching and rollback.

## Examples

```bash theme={null}
# Show current session
contree session

# List all sessions
contree session list

# Show full history
contree session show

# Create and switch to a branch
contree session branch experiment
contree session checkout experiment

# Switch back
contree session checkout main

# Create a branch from another branch
contree session branch hotfix --from main

# List branches (* marks active)
contree session branch

# Undo last operation
contree session rollback

# Undo last 3 operations (`--` stops argparse from eating `-3` as a flag)
contree session rollback -- -3

# Forward one entry
contree session rollback +1

# Absolute jump to a specific history id (use `session show` first)
contree session rollback 42

# Import image from another session
contree session use other-session

# Delete a session
contree session delete my-old-session
contree session rm my-old-session -y
```

## Help output

\$ contree session --help<pre>``usage: contree session [-h]                       {list,ls,use,branch,br,checkout,co,rollback,rb,show,wait,delete,rm,del} ...Manage session branches and history.Without a subcommand, shows the current session info (key, branch,image, last operation).Subcommands:  list (ls)       List all sessions  use KEY         Import another session's current image  branch (br)     List or create branches (--from to fork)  checkout (co)   Switch active branch  rollback (rb)   Navigate history: N=absolute, -N=back, +N=forward  show            Display the session history DAGpositional arguments:  {list,ls,use,branch,br,checkout,co,rollback,rb,show,wait,delete,rm,del}    list (ls)           List all sessions    use                 Import another session's image    branch (br)         List, create, delete, or prune branches    checkout (co)       Switch active branch    rollback (rb)       Navigate history: N=absolute, -N=back, +N=forward    show                Show session history    wait                Drain detached ops in the current session    delete (rm, del)    Delete sessions by keyoptions:  -h, --help            show this help message and exitfor coding agents:  session (no subcommand) is read-only  branch/checkout/rollback/session use mutates local session pointers  `session show` defaults to last 20 history entries; pass -a/--all for full DAG  use `session show` to inspect history DAG before destructive navigation  `session wait [OPS...]` waits for active or specified operationsagent note:  Before using this command in an automated workflow, read:    contree agent``</pre>

## Concepts

Each non-disposable `contree run` creates a new history entry and advances
the branch pointer. Branches share the underlying history – creating a
branch just adds a new pointer at the current position.

Rollback moves the branch pointer backwards. History entries are preserved
and can be recovered by creating a new branch.

## Subcommands

### `session list`

`contree session list` (alias `ls`) prints every session known to the
current profile, with the active session marked. The optional
`--filter` flag narrows the list by substring match against the session
key, which is handy when you keep many disposable sessions named after
features or tickets.

\$ contree session list --help<pre>`usage: contree session list [-h] [--filter FILTER_TEXT]List locally known sessions and their current branch/image.options:  -h, --help            show this help message and exit  --filter FILTER_TEXT  Filter session keys containing this textfor coding agents: read-only command`</pre>

### `session use`

`contree session use KEY` imports the **current image** of another
session into the active session as a new history entry. The source
session is not modified; this is a “fork the snapshot, keep working
here” operation, distinct from the top-level `contree use` which starts
or resumes a session against an image reference.

\$ contree session use --help<pre>`usage: contree session use [-h] session_nameSet current session image to another session's tip image. Accepts exact key or key suffix.positional arguments:  session_name  Session key or suffix to matchoptions:  -h, --help    show this help message and exitfor coding agents: mutates current session history`</pre>

### `session branch`

`contree session branch` (alias `br`) lists branches with `*` marking
the active one. Pass a name to create a new branch pointing at the
current history position, or combine with `--from BRANCH` to fork off a
different branch. The `-U`/`--prune` flag removes branches that no
longer reference live history.

\$ contree session branch --help<pre>`usage: contree session branch [-h] [--from FROM_BRANCH] [-U] [--prune] [branch_name]List branches (no args). Create with NAME (optionally --from). Delete with --delete NAME. Prunedisposable-/detached- branches with --prune.positional arguments:  branch_name         Branch name (create/delete target)options:  -h, --help          show this help message and exit  --from FROM_BRANCH  Source branch (default: active branch)  -U, --delete, --rm  Delete the specified branch (NAME required, must not be active)  --prune             Prune disposable-/detached- branches (non-active only)for coding agents: read-only when NAME/--delete/--prune omitted mutating whencreating/deleting/pruning`</pre>

### `session checkout`

`contree session checkout BRANCH` (alias `co`) switches the active
branch pointer. Working directory, pending files, and the current
image are all reset to whatever the target branch currently points at,
so it is the safe way to bounce between parallel experiments.

\$ contree session checkout --help<pre>`usage: contree session checkout [-h] checkout_branchMove current session to another existing branch tip.positional arguments:  checkout_branch  Branch to switch tooptions:  -h, --help       show this help message and exitfor coding agents: mutates active branch pointer`</pre>

### `session rollback`

`contree session rollback [TARGET]` (alias `rb`) navigates the history
of the current branch. With no argument it steps back one entry; a
positive number jumps to that absolute history index, `-N` steps back
`N` entries, and `+N` steps forward. History entries are preserved –
rollback only moves the branch pointer.

\$ contree session rollback --help<pre>``usage: contree session rollback [-h] [target]Move branch pointer in session history. Supports absolute ID, relative backward (-N), and forward(+N).positional arguments:  target      History target: ID (absolute), -N (back), +N (forward) — use `-- -N` for negative              valuesoptions:  -h, --help  show this help message and exitfor coding agents: mutates active branch history pointer``</pre>

### `session show`

`contree session show` prints the session history DAG with one row per
entry, including operation IDs, image UUIDs, branch pointers, and
relative timestamps. Use `-a` to include hidden entries, `-k KIND` to
filter by entry kind (e.g. `run`, `cd`), and `-l LAST` to show only the
last N rows.

\$ contree session show --help<pre>`usage: contree session show [-h] [-a] [-k KIND] [-l LAST] [--since SINCE] [--until UNTIL]                            [session_name]Print session history DAG entries and branch labels. By default shows last 20 entries; use-a/--all for full history.positional arguments:  session_name     Session key or suffix (default: current session)options:  -h, --help       show this help message and exit  -a, --all        Show full history (default: last 20 entries)  -k, --kind KIND  Filter history entries by kind (e.g., run, use, cd)  -l, --last LAST  Show last N entries after filtering  --since SINCE    Show entries since. Parse +/- intervals (bare seconds or smhdMy) or ISO/date to                   UTC datetime.  --until UNTIL    Show entries before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date                   to UTC datetime.for coding agents: read-only command`</pre>

### `session wait`

`contree session wait [OP_ID ...]` blocks until the specified operations
reach a terminal state (`SUCCESS`, `FAILED`, or `CANCELLED`). When no
IDs are given it waits for every active operation in the session, which
is the canonical way to drain background `contree run -d` jobs before
moving on.

\$ contree session wait --help<pre>`` usage: contree session wait [-h] [UUID_OR_REF ...]Drain detached operations in the current session. With no arguments, reads the session's pending-ops cache, polls each to a terminal status, and advances the active branch to each non-disposableresult image (recording `disposable-<uuid>` branches for disposable runs). With explicit UUIDs,this command degrades to a plain polling loop: it prints completion rows but does NOT touch theactive branch, because the pending metadata is not loaded for explicit UUIDs.positional arguments:  UUID_OR_REF  Operations to wait for (default: all active in this session). Accepts UUIDs and               session-history references (HEAD, HEAD~N, @, @N, @-N, @+N, :N, bare N).options:  -h, --help   show this help message and exitfor coding agents: no-arg form mutates session history (advances active branch) UUID form is apure polling observer if you need result images from explicit UUIDs, use `op show UUID | jq -r.image` and `contree use` ``</pre>

### `session delete`

`contree session delete KEY [KEY ...]` (aliases `rm`, `del`) removes
sessions and all their data – history, branches, pending files, shell
history. The command prompts before deleting unless `-y` is passed.
Use this to garbage-collect throwaway sessions; the disk savings on
the SQLite database can be substantial when many short-lived sessions
accumulate.

\$ contree session delete --help<pre>`usage: contree session delete [-h] [-f] KEY [KEY ...]positional arguments:  KEY              Session keys to deleteoptions:  -h, --help       show this help message and exit  -f, -y, --force  Do not ask for confirmation`</pre>

```bash theme={null}
contree session delete KEY [KEY ...]
contree session rm KEY -y     # skip confirmation
contree session del KEY
```

## See also

* [Sessions, Branches & Rollback](https://docs.tokenfactory.nebius.com/sandboxes/cli/tutorial/sessions.md) – full tutorial on sessions, branches, and rollback
* [use - Choose an image for the session](https://docs.tokenfactory.nebius.com/sandboxes/cli/commands/use.md) – start or resume a session
