Skip to main content
contree shell starts a REPL that combines management commands and sandbox execution in a single session. It is the fastest way to explore images, run commands, edit files, and manage branches – all without leaving the prompt.

​
Starting the shell

The shell needs a session, just like any other command. You can pin one explicitly or let it auto-generate:
The shell prints a coloured prompt showing the current working directory:
If the session already has an image (from a previous contree use), the shell resumes it. Otherwise, set one first:

​
Running commands

Type any command and it runs inside the sandbox:
Each command is an implicit contree run with shell=True. The whole input line is forwarded verbatim to the remote sh -c, so pipes, redirects, ;, &&, and || are interpreted by the sandbox shell exactly as typed:
Quoting from your local prompt is also preserved through to the remote shell:
You can also use the explicit form, which is equivalent:
The explicit contree run prefix is required when you need flags like -D (disposable), -e (env), -t (timeout), --file, or -d (detach):

​
Tab completion

The shell supports context-aware tab completion for nearly everything. Press Tab at any point to see available completions.

​
What completes

Commands and subcommands – type contree then Tab to see all available subcommands. Type a partial name and Tab completes it:
Flags – type - or -- after a command and Tab shows available flags:
Sandbox paths – any command that takes a file path completes against the actual sandbox filesystem. The shell queries the image via the inspect API and caches the results:
Directory-only paths – cd completes only directories:
Images – contree use and contree tag complete image references. Type tag: to filter by tag names, or start typing a UUID:
Operations – contree show and contree kill complete operation UUIDs:
Branches and sessions – session management subcommands complete branch names and session keys:
Help topics – help completes all command and alias names:

​
What does not complete

Bare commands (implicit run) do not have tab completion. The shell does not know what executables exist inside the sandbox, so typing a bare command name and pressing Tab will not offer suggestions:
However, paths starting with / do complete even in bare command context:

​
Aliases

The shell intercepts several bare command names for convenience:

​
ls and cat

Bare ls and cat are forwarded as contree API commands – they inspect the sandbox filesystem without spawning a new instance:
This is equivalent to contree ls and contree cat. To run the actual ls or cat binary inside the sandbox instead, use the explicit prefix:
When pending files exist (from contree file edit or contree file cp), ls and cat automatically fall back to running inside the sandbox so the pending files are visible.The same fallback happens when arguments contain flags (-l) or glob characters (*, ?, [).

​
vim, vi, nvim, nano

Editor names open contree file edit with the corresponding host editor:
This downloads the file, opens it in vim on your machine, and stages any changes as a pending file for the next run.

​
Builtins

​
cd

Change the working directory for subsequent commands:
cd without arguments resets to the sandbox’s default working directory.
cd does not validate that the path exists in the sandbox. Errors surface only when the next command uses the invalid path.

​
pwd

Print the current working directory:

​
history

Show command history for the current session, optionally filtered by a case-insensitive substring:
History is persisted in SQLite per session (up to 10,000 lines) and restored when you re-enter the shell. Search is scoped to the current session key; different sessions have isolated history.

​
help

Show general shell help, or help for a specific command or builtin:
Bare help prints an overview of builtins, aliases, line continuation, and tab completion. help <topic> shows detailed help for a builtin, alias, or contree command.

​
clear

Clear the terminal screen:

​
timeout

Run a command with a server-enforced operation timeout. Mirrors the GNU timeout convention but sets payload.timeout on the API request instead of spawning a local wrapper inside the sandbox:
DURATION accepts a bare integer or decimal (seconds by default) and the suffixes s, m, h, d. When the value cannot be parsed, the shell forwards the line untouched so the in-image timeout binary still handles advanced flags like --kill-after or -s SIGTERM. When the limit fires, the API returns state.timed_out=true (status may still be SUCCESS with signal=9), and the shell logs:

​
--format / -f

Change the output format mid-session, or show the current format:

​
Workflow example

A typical shell session putting it all together:

​
Limitations

  • Output format is fixed – the --format flag is set at contree shell launch. To use JSON output: contree -o json shell.
  • No local pipes or redirects – |, >, < are sent to the sandbox, not interpreted locally.
  • No job control – no &, bg, fg, or Ctrl-Z. Use contree run -d for detached execution.
  • Bare commands use defaults – you cannot pass --env, --file, or --disposable without the explicit contree run prefix. The operation timeout has a shell shortcut: timeout DURATION CMD... (see above).
  • No ~ or glob expansion – these tokens are passed as-is to the sandbox.
  • Image list cache – newly created images during a session won’t appear in tab completion until the shell is restarted. Path completions are cached per image and refresh when the session image advances.
The shell is the fastest way to iterate. Next: Sessions, Branches & Rollback.