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

positional 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 key

options:
  -h, --help            show this help message and exit

for 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 operations

agent note:
  Before using this command in an automated workflow, read:
    contree agent
## 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
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 text

for coding agents: read-only command
### `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
usage: contree session use \[-h] session\_name

Set current session image to another session's tip image. Accepts exact key or key suffix.

positional arguments:
  session\_name  Session key or suffix to match

options:
  -h, --help    show this help message and exit

for coding agents: mutates current session history
### `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
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. Prune
disposable-/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 when
creating/deleting/pruning
### `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
usage: contree session checkout \[-h] checkout\_branch

Move current session to another existing branch tip.

positional arguments:
  checkout\_branch  Branch to switch to

options:
  -h, --help       show this help message and exit

for coding agents: mutates active branch pointer
### `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
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
              values

options:
  -h, --help  show this help message and exit

for coding agents: mutates active branch history pointer
### `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
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
### `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
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-disposable
result image (recording \`disposable-\\` branches for disposable runs). With explicit UUIDs,
this command degrades to a plain polling loop: it prints completion rows but does NOT touch the
active 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 exit

for coding agents: no-arg form mutates session history (advances active branch) UUID form is a
pure polling observer if you need result images from explicit UUIDs, use \`op show UUID | jq -r
.image\` and \`contree use\`
### `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
usage: contree session delete \[-h] \[-y] KEY \[KEY ...]

positional arguments:
  KEY          Session keys to delete

options:
  -h, --help   show this help message and exit
  -y, --force  Do not ask for confirmation
```bash theme={null} contree session delete KEY [KEY ...] contree session rm KEY -y # skip confirmation contree session del KEY ``` ## See also * [Sessions, Branches & Rollback](../tutorial/sessions) – full tutorial on sessions, branches, and rollback * [use - Choose an image for the session](./use) – start or resume a session