> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# shell - Interactive REPL

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

## Help output

<div className="contree-terminal" style={{"border":"1px solid rgba(255,255,255,0.15)","borderRadius":8,"overflow":"hidden","margin":"1rem 0"}}><div style={{"background":"#292929","height":24,"display":"flex","alignItems":"center","padding":"0 12px","position":"relative"}}><div style={{"display":"flex","alignItems":"center","flexShrink":0}}><span style={{"display":"inline-block","width":10,"height":10,"borderRadius":"50%","background":"#ff5f57","marginRight":6}} /><span style={{"display":"inline-block","width":10,"height":10,"borderRadius":"50%","background":"#febc2e","marginRight":6}} /><span style={{"display":"inline-block","width":10,"height":10,"borderRadius":"50%","background":"#28c840"}} /></div><div style={{"position":"absolute","left":0,"right":0,"textAlign":"center","fontFamily":"-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif","fontWeight":"bold","color":"#999"}}>\$ contree shell --help</div></div><pre style={{"margin":0,"borderRadius":0,"padding":"8px 10px","background":"#1e1e1e","overflowX":"auto"}}><code style={{"fontFamily":"JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Monaco, Cascadia Mono, Segoe UI Mono, Roboto Mono, Oxygen Mono, Ubuntu Monospace, Source Code Pro, Fira Mono, Droid Sans Mono, Consolas, Courier New, monospace","color":"#c5c8c6","whiteSpace":"pre-wrap"}}><span style={{"color":"#61afef","fontWeight":"bold"}}>usage: </span><span style={{"color":"#c678dd","fontWeight":"bold"}}>contree shell</span><span style={{"color":"#c5c8c6"}}> \[</span><span style={{"color":"#98c379"}}>-h</span><span style={{"color":"#c5c8c6"}}>]</span><br /><br /><span style={{"color":"#c5c8c6"}}>Start an interactive shell session.</span><br /><br /><span style={{"color":"#c5c8c6"}}>Launches a REPL where bare commands (e.g. \`apt install curl\`) are</span><br /><span style={{"color":"#c5c8c6"}}>executed in the session sandbox via \`run --shell\`, and prefixed</span><br /><span style={{"color":"#c5c8c6"}}>commands (e.g. \`contree ls /etc\`) are dispatched as management</span><br /><span style={{"color":"#c5c8c6"}}>commands.</span><br /><br /><span style={{"color":"#c5c8c6"}}>Built-in commands: cd, pwd, history, help, exit/quit.</span><br /><span style={{"color":"#c5c8c6"}}>Tab completion for commands, flags, image paths, tags, and branches.</span><br /><br /><span style={{"color":"#61afef","fontWeight":"bold"}}>options:</span><br /><span style={{"color":"#c5c8c6"}}>  </span><span style={{"color":"#98c379","fontWeight":"bold"}}>-h</span><span style={{"color":"#c5c8c6"}}>, </span><span style={{"color":"#56b6c2","fontWeight":"bold"}}>--help</span><span style={{"color":"#c5c8c6"}}>  show this help message and exit</span><br /><br /><span style={{"color":"#c5c8c6"}}>for coding agents:</span><br /><span style={{"color":"#c5c8c6"}}>  bare commands are implicit \`contree run --shell\`</span><br /><span style={{"color":"#c5c8c6"}}>  management commands must be prefixed with \`contree\`</span><br /><span style={{"color":"#c5c8c6"}}>  exit with \`exit\`/\`quit\` or Ctrl-D</span><br /><br /><span style={{"color":"#c5c8c6"}}>agent note:</span><br /><span style={{"color":"#c5c8c6"}}>  Before using this command in an automated workflow, read:</span><br /><span style={{"color":"#c5c8c6"}}>    contree agent</span></code></pre></div>

## Examples

```bash theme={null}
# 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:

```text theme={null}
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`:

```text theme={null}
apt-get install -y curl
echo hello && ls /
```

**Prefixed commands** — `contree ...` dispatches management commands through
the same argparse parser as the CLI:

```text theme={null}
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.
</Note>

## 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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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](../tutorial/shell) – full tutorial on using the interactive shell
* [run - Execute a command in the sandbox](./run) – the `run` command used by implicit bare commands
* [file - Stage file edits for the next run](./file) – the `file edit` command behind editor aliases