Skip to main content
Set the session image or show the current session state. This is typically the first command you run – it tells contree-cli which image to use for subsequent commands.

​
Examples

# Start a session with an image
eval $(contree use tag:ubuntu:latest)

# Start a session with a specific image UUID
eval $(contree use 3f2a7b...)

# Start or resume a named session
export CONTREE_SESSION=my-session

# Show current session info
contree use

# Start a fresh session (new session key)
eval $(contree use -N tag:python:3.11-slim)
The eval wrapper exports CONTREE_SESSION into your shell so all subsequent commands share the same session. Without eval, contree prints the export line but your shell doesn’t pick it up.

​
Help output

$ contree use —help
usage: contree use [-h] [-N] [image]

Set or show the current session image.

With an IMAGE argument, resolves it (UUID or tag:NAME) and sets it as
the active session image. Prints a shell export line so that the
session key can be captured with eval:

  eval $(contree use tag:ubuntu:latest)

Without arguments, displays the current session info (image, branch,
last operation).

Use -N/—new to start a fresh session instead of resuming the current
one. The new session key is printed as an export line.

positional arguments:
  image       Image UUID or tag

options:
  -h, —help  show this help message and exit
  -N, —new   Start a new session instead of resuming the current one

for coding agents:
  use IMAGE starts/switches a session and prints CONTREE_SESSION export
  use (without IMAGE) is read-only and prints current session state
  use —new IMAGE creates a fresh session key
  without CONTREE_SESSION env var, key is auto-generated as <cwd>+<8hex>
  (derived from profile+ppid+tty); export your own for stability

agent note:
  Before using this command in an automated workflow, read:
    contree agent

​
Behavior

With an image argument: resolves the image (UUID or tag:NAME), sets it as the session’s current image, and prints a shell export statement. Without arguments: displays the current session info – session key, active branch, current image, and last operation. With --new: generates a new random session key instead of resuming the existing one. Useful when you want a clean slate in the same terminal.

​
Shell detection

The output format adapts to your shell:
  • bash / zsh: export CONTREE_SESSION=<key>
  • fish: set -gx CONTREE_SESSION <key>
Detection uses the $SHELL environment variable.

​
See also