Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Interactive Mode

A task whose command drops you into a shell, or otherwise needs your input, works with nothing to configure: there is no interactive field in either format, and the same task is interactive under both binaries. This page is the one description of what that means — which container is eligible, what it gets, when a real terminal is allocated, and how the container learns what kind of terminal it has. The examples are ratect.toml; the batect.yml spelling is the same fields with the same meaning.

[tasks.shell]
description = "Start a shell in the app's environment"
group = "Utilities"
run = { container = "dev", command = "bash" }

ratect run shell lands you in bash inside dev, with your keystrokes reaching it and its output reaching you. That is the full-stack example’s own shell task; each project on Worked Examples carries one too.

Which container is eligible

Each task’s own container — the task named on the command line, and every prerequisite it runs, however deeply nested. A dependency’s or a sidecar’s container is never interactive. Prerequisites run one after another, and each task container is attached to Ratect’s stdin only while it runs. Whatever input is waiting meanwhile is forwarded to it, whether or not it reads it, so a prerequisite takes piped input ahead of the named task. If the pipe ends while it runs, the named task’s stdin is closed from the start. What you type at a terminal goes to the task container running at the time; what you type between two of them waits for the next.

What the eligible container gets

Always, independent of whether Ratect’s own stdin and stdout are terminals, its stdin forwarded from Ratect’s own, so piped input reaches the container — including its end: when Ratect’s own stdin closes, so does the container’s, and a process that reads until end of input (cat, a stdio server) exits. (The host’s TERM isn’t the eligible container’s alone: every container gets it — see TERM propagation below.)

Additionally, when both Ratect’s own stdin and stdout are real terminals, a real Docker TTY: the local terminal goes into raw mode for the session, so a full-screen program (an editor, top, a REPL with line editing) renders as it would in a shell. The terminal is restored when the session ends; if that fails, a warning says so and names the fix (reset or stty sane). A raw terminal sends Ctrl+C to the container as a keystroke, as docker run -it does, so it interrupts the program in the container rather than the run — and a command running as the container’s main process with no handler of its own ignores it. Piped output, a redirected non-terminal, or a CI job gets plain stdin forwarding and streamed output instead — stdin still reaches the container either way.

The one exception is --output all, whose line-prefixed output can’t host an interactive session: under it no container gets a TTY or stdin, and every container gets TERM=dumb instead, matching Batect.

Terminal resizing

When a TTY is allocated, the container’s stays in sync with the local terminal’s size for the whole session, not just once at the start — a local resize is forwarded live, via a SIGWINCH handler. That tracking is Unix-only; on other platforms the size is synced once, at the start of the session, and not tracked further. Interactive mode itself works on every platform.

TERM propagation

Ratect’s own TERM environment variable is copied into the environment of every container a run creates — the invoked task’s own, each prerequisite’s, and every dependency and sidecar — whether or not that container is eligible, matching Batect. Under --output all every container gets TERM=dumb instead. It isn’t gated on a real TTY actually being allocated either, so a full-screen program inside the container knows the terminal type even when piped output lets it detect that it isn’t attached to a real TTY. Never applied to an image build.

Where it sits among the container’s other environment variables — what overrides it on a key collision — is Environment precedence.

Coming from Batect? One known, deliberate divergence: Batect’s real-TTY gate checks only whether its output is a real terminal; Ratect’s requires both stdin and stdout to be. It is listed, with the Unix-only resize tracking, under Differences from Batect.