use

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