Manage session branches and history. Sessions track the image state as you
run commands, with support for branching and rollback.
Examples
# 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
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-<uuid>` 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
contree session delete KEY [KEY ...]
contree session rm KEY -y # skip confirmation
contree session del KEY
See also
