shell

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 [N]	Show command history (optional limit)
help [TOPIC]	Show help (optionally for a specific command)
clear	Clear the terminal screen
--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.

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.

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: No way to pass --timeout, --env, or --file without the explicit contree run prefix.

• 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 – the run command used by implicit bare commands

• file – the file edit command behind editor aliases