Start an interactive REPL for managing sessions and running sandbox commands.
Help output
usage: contree shell [-h]
Start an interactive shell session.
Launches a REPL where bare commands (e.g. `apt install curl`) are
executed in the session sandbox via `run —shell`, and prefixed
commands (e.g. `contree ls /etc`) are dispatched as management
commands.
Built-in commands: cd, pwd, history, help, exit/quit.
Tab completion for commands, flags, image paths, tags, and branches.
options:
-h, —help show this help message and exit
for coding agents:
bare commands are implicit `contree run —shell`
management commands must be prefixed with `contree`
exit with `exit`/`quit` or Ctrl-D
agent note:
Before using this command in an automated workflow, read:
contree agent
Examples
# Start the shell
contree shell
# Start with a specific output format
contree -f json shell
# Start with a named profile
contree --profile=personal shell
Prompt
The prompt shows the current working directory:
contree:/> apt-get update -qq
contree:/app> python main.py
Command dispatch
The shell recognises four types of input:
Bare commands — executed inside the sandbox as an implicit contree run
with shell=True:
apt-get install -y curl
echo hello && ls /
contree ... dispatches management commands through
the same argparse parser as the CLI:
contree ls /etc
contree session branch experiment
contree run -e DEBUG=1 -- ./app
| Builtin | Description |
|---|
cd [PATH] | Change working directory (cd - for previous) |
pwd | Print working directory |
history [SEARCH] | Show command history, optionally filtered by substring |
help [TOPIC] | Show help (optionally for a specific command) |
clear | Clear the terminal screen |
timeout DURATION CMD... | Run CMD... with the API operation timeout set to DURATION |
--format NAME / -f NAME | Change output format (or show current if no argument) |
exit / quit | Exit the shell (also Ctrl-D) |
| Alias | Equivalent |
|---|
ls [PATH] | contree ls [PATH] (API inspect, no sandbox) |
cat PATH | contree cat PATH (API inspect, no sandbox) |
vim PATH | contree file edit PATH (with EDITOR=vim) |
vi PATH | contree file edit PATH (with EDITOR=vi) |
nvim PATH | contree file edit PATH (with EDITOR=nvim) |
nano PATH | contree file edit PATH (with EDITOR=nano) |
ls and cat aliases fall back to running inside the sandbox when pending
files exist or when args contain flags or glob characters.
Implicit run: shell-expression passthrough
Bare commands are forwarded to the sandbox as a single shell expression with
shell=True. The entire input line is sent verbatim to the remote sh -c,
so operators like |, ;, &&, ||, >, < are interpreted by the
remote shell exactly as typed:
contree:/> mount | grep cgroup
contree:/> echo 1 ; echo 2
contree:/> apt-get update && apt-get install -y curl
contree:/> uname -a > /tmp/info.txt
contree:/> python3 -c "print('hello world')"
timeout builtin
The shell recognises timeout DURATION CMD... and sets the server-side
operation timeout to DURATION instead of running the GNU timeout binary
inside the sandbox. The kill is enforced by the API, not by a wrapper
process, so the operation surfaces a warning when the limit is hit:
contree:/> timeout 30 apk add gcc
contree:/> timeout 5m make build
contree:/> timeout 1h python long_train.py
DURATION is an integer or decimal optionally followed by a unit suffix:
| Suffix | Meaning |
|---|
| (none) | Seconds |
s | Seconds |
m | Minutes |
h | Hours |
d | Days |
DURATION is not a valid spec (for example timeout --kill-after=5 30 cmd
or timeout --help), the shell falls through and sends the line to the
sandbox unchanged, so the in-image timeout binary still handles advanced
flags.
When the limit is hit, the response carries state.timed_out=true and the
shell logs:
WARNING: Operation <uuid> timed out after 30s
Tab completion
The shell provides context-aware tab completion for almost everything
except bare (implicit run) commands. Press Tab to complete:
| Context | What completes |
|---|
| Empty prompt | All commands, aliases, and builtins |
contree <TAB> | Subcommand names |
contree CMD -<TAB> | Flags for that command |
contree CMD --<TAB> | Long flags for that command |
ls /etc/<TAB>, cat /etc/<TAB> | Sandbox file paths |
cd /us<TAB> | Sandbox directory paths (dirs only) |
vim /etc/<TAB>, nano /etc/<TAB> | Sandbox file paths |
contree use <TAB> | Image UUIDs and tag:NAME |
contree tag <TAB> | Image UUIDs and tag:NAME |
contree show <TAB> | Operation UUIDs |
contree kill <TAB> | Operation UUIDs |
contree session checkout <TAB> | Branch names |
contree session branch <TAB> | Branch names |
contree session use <TAB> | Session keys |
contree file edit <TAB> | Sandbox file paths |
help <TAB> | All command and alias names |
History search
The history builtin takes an optional pattern and filters the
persisted history by case-insensitive substring:
contree:/> history # show every entry for this session
contree:/> history apt # any line containing "apt"
contree:/> history 'contree ' # exact "contree " (with trailing space)
contree:/> history make # any line containing "make"
session_key’s
entries. Up to 10,000 lines are kept; older lines are trimmed on save.
Line continuation
A trailing \ at the end of input triggers a > continuation prompt,
just like traditional shells:
contree:/> ls \
> -alh \
> /sys
ls -alh /sys). Unclosed quotes also trigger continuation,
preserving the newline inside the quoted string.
Limitations
- No global flags on commands:
--token, --url, --log-level are
not available inside the shell.
- No local pipes or redirects:
|, >, < are passed as-is to the
sandbox (works for remote commands, not for contree output).
- No job control: No
&, bg, fg, or Ctrl-Z. Use contree run -d
for background tasks.
- Bare commands use defaults:
--env, --file, --disposable, and
--detach require the explicit contree run prefix. The operation
timeout has a shorthand: timeout DURATION CMD... (see above).
- No
~ or glob expansion: Passed as-is to the sandbox.
- Cannot nest shells: Running
contree shell inside a shell is not
supported.
See also
