shell - Interactive REPL

Start an interactive REPL for managing sessions and running sandbox commands.

Help output

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 /

Prefixed commands — 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

Builtins – handled locally by the shell:

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)

Aliases — bare names intercepted for convenience:

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)

Note

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

There is no local tokenize/rejoin step, so quoting is preserved:

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

If 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

Path completions query the sandbox filesystem via the inspect API and are cached persistently – subsequent completions for the same directory are instant.

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"

History is per-session: searches see only the current 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

Backslash-newline pairs are removed to join the lines into a single command (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

• Interactive Shell – full tutorial on using the interactive shell

• run - Execute a command in the sandbox – the run command used by implicit bare commands

• file - Stage file edits for the next run – the file edit command behind editor aliases