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

Output Styles

--output/-o controls how much Ratect says about its own progress, and never where anything goes. What the task’s command prints streams through as written in every style but all, which prefixes each of its lines with the container’s name, as it does every other line. Both binaries take it (ratect on every command, ratect-compat on every invocation) and render each style with the same code (ui.rs), so this page is the one description of the four styles; the ratect and ratect-compat CLI references only link here.

Streams

Stdout is the result; stderr is everything said about producing it (decisions/0017). For a run, the result is the task container’s own output. Everything else — progress, the summary line, notices, warnings and errors — is about the run, and -o shapes how much of it is said, not which stream it is said on.

The two binaries differ in one thing: where their progress goes.

  • ratect writes its progress — the milestones, the summary line, and under all the prefixed lines of every container but the task’s own — to stderr. Its stdout is the task container’s output and nothing else, in every style (under all, each line prefixed with the container’s name), so ratect run test > out.txt captures the result alone and 2>/dev/null silences the conversation without touching it.
  • ratect-compat writes its progress to stdout, where Batect does, because a Batect project’s scripts may read it. Under simple those lines share stdout with the task’s own output, unmarked, exactly as under Batect; -o quiet is the escape for a script that needs stdout to be the container’s output alone, and -o all prefixes every line.

Three kinds of line reach stderr in every style, quiet included, from both binaries, whatever RUST_LOG is set to: an error (Error: in bold red, then the message), a warning (Warning: in bold yellow — a deprecated flag, a proxy bound to loopback that containers can’t reach, a credential helper that failed), and a notice (unmarked: the interrupt notice with its “press Ctrl+C again” instructions, the Cleanup complete. that follows it once cleanup is over, and what --no-cleanup* left in place and how to remove it). Only the fourth kind, progress, is shaped by -o. RUST_LOG filters Ratect’s internal diagnostics (Filtering RUST_LOG), which are a separate stream of breadcrumbs on stderr; nothing a user needs to act on is behind it.

A task’s own non-zero exit is reported by the exit code and, outside quiet, by the summary line — never by an Error: line; a run ended by a signal is reported by the interrupt notice and its exit code, and ends with Cleanup complete. (or the error saying what cleanup left behind) rather than a trailing Error: Interrupted. Error: is reserved for Ratect’s own failures: it could not run the task, or could not clean up after it. A failure to run a task that has started — an image that won’t pull, a dependency that never becomes healthy — is reported when it happens, before any cleanup line, and outside quiet the run then ends with the summary line’s other form, <task> failed after <duration>., where finished with exit code N would have gone. So does a run whose command exited 0 but whose cleanup then failed, after the error saying what was left behind; a command that exited non-zero keeps its finished with exit code N line whatever cleanup does. A failure before any task starts, such as a config that doesn’t load, is printed as the run exits, with no summary line, as is a prerequisite’s failure for the task waiting on it: the prerequisite’s own line is the one printed.

In every style, and in every command’s own output, a control character in a name or value from your configuration (a task, container, image or cache name, a path, a command, a Git include’s repo or ref), or in image build output, is printed escaped: \u{1b} for ESC, \r for a carriage return. A Git bundle or a config file can’t send your terminal escape sequences that way. A name’s or value’s line breaks and tabs are escaped too (\n, \t), error messages included, so neither can add a line of its own. A command and image build output keep theirs, as does the output of a program an error quotes, such as git’s. A container’s own output is printed as it was written.

Each style is shown below from the same real run — ratect run journey-test against examples/full-stack — so you compare styles rather than projects.

When --output isn’t given, Ratect auto-selects: fancy on an interactive console (the stream its progress goes to — stderr for ratect, stdout for ratect-compat — is a real terminal, TERM is set and not dumb, the terminal size is queryable, and there is no --no-color); simple otherwise. quiet and all are never auto-selected; ratect services up is the exception, which always uses all and refuses any other -o. So ratect run test > out.txt on a terminal still gets fancy — the pipe took the result, not the conversation — where ratect-compat test > out.txt gets simple.

fancy

The same real recording as the homepage, unedited — static text can’t convey an in-place repaint:

What the recording can’t tell you: there is no spinner — the animation is purely rewriting the block’s lines in place, as Batect’s is — and lines are clipped to the terminal’s current width. After that width changes, the block is drawn afresh below the old one rather than over it, since the terminal has re-wrapped the old lines. Because it repaints, it needs a terminal: an explicit -o fancy asks less than auto-selection does — TERM may be unset, but not dumb — and fails up front, with an error naming the reason, when the stream it checked isn’t a terminal, TERM is dumb, or the terminal size can’t be determined (Batect instead accepts it, then crashes on the first repaint when stdout isn’t a terminal, or garbles a TERM=dumb terminal with cursor movements it can’t perform). Works with --no-color — the repaint stays; bold/color go — a combination Batect rejects.

simple

ratect run journey-test -o simple, captured on a terminal in examples/full-stack:

Running journey-test...
Starting cache...
Starting db...
Started cache.
Started db.
cache has become healthy.
db has become healthy.
Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1) in db...
db has completed all setup commands.
Starting app...
Started app.
app has become healthy.
Running sh -c 'npm ci && node test.js' in journey-test...

added 6 packages, and audited 7 packages in 983ms

found 0 vulnerabilities
app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
cache holds visits:count=1000001, confirming app and this container share the same cache
journey test passed

Cleaning up...
journey-test finished with exit code 0 in 9.1s.

Append-only, with no live-updating progress detail at all, so it is safe for CI logs and redirected output. A dependency that exits on its own while the task runs is reported as a milestone (db exited unexpectedly with exit code 137.), not a warning — the run’s failure, if one follows, is what explains it. The health/setup-command milestones are shown for dependency containers only. Under ratect the task’s own container has no readiness gate to report (see Dependency Readiness); under ratect-compat its readiness runs concurrently with its command (see task lifecycle), so printing them would drop a line into the middle of that command’s own output — all shows them. A readiness failure is still reported, on stderr, in every style.

Cleanup opens with Cleaning up..., or, when it follows a failure, names it — Cleaning up after journey-test exited with code 3..., or, when the task couldn’t run, the step and container that failed: Cleaning up after db did not become healthy..., Cleaning up after db's setup command 1 exited with code 3..., Cleaning up after cache's image failed to pull.... The Error: above it says why. all opens it the same way.

quiet

ratect run journey-test -o quiet, captured the same way:


added 6 packages, and audited 7 packages in 1s

found 0 vulnerabilities
app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
cache holds visits:count=1000001, confirming app and this container share the same cache
journey test passed

No progress at all: stdout is exactly the task container’s own output (under ratect it is in every style but all, which prefixes each line with the container’s name; quiet is where ratect-compat matches it), and stderr carries only errors, warnings and notices. Nothing from app/db/cache — a dependency’s own stdout is never shown outside all, whatever the style.

quiet also switches a task listing (ratect tasks list, ratect-compat --list-tasks) to a machine-readable format: one task per line, sorted by name, as name alone or name<TAB>description — no header, no grouping. The ratect commands with a listing of their own (services list, caches, includes, resources, doctor) each have a quiet form of the same kind, described with the command in the ratect CLI reference.

all

ratect run journey-test -o all, captured the same way — long, because every line db, cache and app wrote during the run is here too:

journey-test | Running journey-test...
db           | Starting container...
cache        | Starting container...
db           | Container started.
cache        | Container started.
db           | ********************************************************************************
db           | WARNING: POSTGRES_HOST_AUTH_METHOD has been set to "trust". This will allow
db           |          anyone with access to the Postgres port to access your database without
db           |          a password, even if POSTGRES_PASSWORD is set. See PostgreSQL
db           |          documentation about "trust":
db           |          https://www.postgresql.org/docs/current/auth-trust.html
db           |          In Docker's default configuration, this is effectively any other
db           |          container on the same system.
db           |
db           |          It is not recommended to use POSTGRES_HOST_AUTH_METHOD=trust. Replace
db           |          it with "-e POSTGRES_PASSWORD=password" instead to set a password in
db           |          "docker run".
db           | ********************************************************************************
cache        | 1:C 28 Oct 2026 19:12:43.874 * oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
cache        | 1:C 28 Oct 2026 19:12:43.874 * Redis version=7.4.11, bits=64, commit=00000000, modified=0, pid=1, just started
cache        | 1:C 28 Oct 2026 19:12:43.874 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
cache        | 1:M 28 Oct 2026 19:12:43.874 * monotonic clock: POSIX clock_gettime
cache        | 1:M 28 Oct 2026 19:12:43.874 * Running mode=standalone, port=6379.
cache        | 1:M 28 Oct 2026 19:12:43.874 * Server initialized
cache        | 1:M 28 Oct 2026 19:12:43.874 * Ready to accept connections tcp
db           | The files belonging to this database system will be owned by user "postgres".
db           | This user must also own the server process.
db           |
db           | The database cluster will be initialized with locale "en_US.utf8".
db           | The default database encoding has accordingly been set to "UTF8".
db           | The default text search configuration will be set to "english".
db           |
db           | Data page checksums are disabled.
db           |
db           | fixing permissions on existing directory /var/lib/postgresql/data ... ok
db           | creating subdirectories ... ok
db           | selecting dynamic shared memory implementation ... posix
db           | selecting default max_connections ... 100
db           | selecting default shared_buffers ... 128MB
db           | selecting default time zone ... Etc/UTC
db           | creating configuration files ... ok
db           | running bootstrap script ... ok
db           | performing post-bootstrap initialization ... ok
cache        | Container became healthy.
db           | syncing data to disk ... ok
db           |
db           |
db           | Success. You can now start the database server using:
db           |
db           |     pg_ctl -D /var/lib/postgresql/data -l logfile start
db           |
db           | initdb: warning: enabling "trust" authentication for local connections
db           | initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.
db           | waiting for server to start....2026-10-28 19:12:44.910 UTC [54] LOG:  starting PostgreSQL 16.15 (Debian 16.15-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
db           | 2026-10-28 19:12:44.911 UTC [54] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db           | 2026-10-28 19:12:44.913 UTC [57] LOG:  database system was shut down at 2026-10-28 19:12:44 UTC
db           | 2026-10-28 19:12:44.915 UTC [54] LOG:  database system is ready to accept connections
db           |  done
db           | server started
db           |
db           | /usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/01-schema.sql
db           | CREATE TABLE
db           | INSERT 0 1000000
db           | CREATE INDEX
db           |
db           |
db           | waiting for server to shut down....2026-10-28 19:12:46.289 UTC [54] LOG:  received fast shutdown request
db           | 2026-10-28 19:12:46.290 UTC [54] LOG:  aborting any active transactions
db           | 2026-10-28 19:12:46.291 UTC [54] LOG:  background worker "logical replication launcher" (PID 60) exited with exit code 1
db           | 2026-10-28 19:12:46.291 UTC [55] LOG:  shutting down
db           | 2026-10-28 19:12:46.292 UTC [55] LOG:  checkpoint starting: shutdown immediate
db           | 2026-10-28 19:12:46.435 UTC [55] LOG:  checkpoint complete: wrote 10152 buffers (62.0%); 0 WAL file(s) added, 0 removed, 10 recycled; write=0.057 s, sync=0.071 s, total=0.144 s; sync files=45, longest=0.028 s, average=0.002 s; distance=174130 kB, estimate=174130 kB; lsn=0/BEFF470, redo lsn=0/BEFF470
db           | 2026-10-28 19:12:46.440 UTC [54] LOG:  database system is shut down
db           |  done
db           | server stopped
db           |
db           | PostgreSQL init process complete; ready for start up.
db           |
db           | 2026-10-28 19:12:46.509 UTC [1] LOG:  starting PostgreSQL 16.15 (Debian 16.15-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
db           | 2026-10-28 19:12:46.510 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
db           | 2026-10-28 19:12:46.510 UTC [1] LOG:  listening on IPv6 address "::", port 5432
db           | 2026-10-28 19:12:46.513 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db           | 2026-10-28 19:12:46.517 UTC [77] LOG:  database system was shut down at 2026-10-28 19:12:46 UTC
db           | 2026-10-28 19:12:46.521 UTC [1] LOG:  database system is ready to accept connections
db           | Container became healthy.
db           | Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1)...
db           | Setup command 1 | ANALYZE
db           | Container has completed all setup commands.
app          | Starting container...
app          | Container started.
app          |
app          | added 99 packages, and audited 100 packages in 993ms
app          |
app          | 18 packages are looking for funding
app          |   run `npm fund` for details
app          |
app          | found 0 vulnerabilities
app          | npm notice
app          | npm notice New major version of npm available! 10.9.8 -> 12.2.1
app          | npm notice Changelog: https://github.com/npm/cli/releases/tag/v12.2.1
app          | npm notice To update run: npm install -g npm@12.2.1
app          | npm notice
app          |
app          | > full-stack-app@1.0.0 start
app          | > node server.js
app          |
app          | Listening on port 8080
app          | Container became healthy.
journey-test | Running sh -c 'npm ci && node test.js'...
journey-test |
journey-test | added 6 packages, and audited 7 packages in 906ms
journey-test |
journey-test | found 0 vulnerabilities
journey-test | app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
journey-test | cache holds visits:count=1000001, confirming app and this container share the same cache
journey-test | journey test passed
journey-test | Cleaning up...
journey-test | Container stopped.
journey-test | Container removed.
app          | Container stopped.
app          | Container removed.
db           | 2026-10-28 19:12:50.860 UTC [1] LOG:  received fast shutdown request
cache        | 1:signal-handler (1793214770) Received SIGTERM scheduling shutdown...
db           | 2026-10-28 19:12:50.861 UTC [1] LOG:  aborting any active transactions
db           | 2026-10-28 19:12:50.862 UTC [1] LOG:  background worker "logical replication launcher" (PID 80) exited with exit code 1
db           | 2026-10-28 19:12:50.862 UTC [75] LOG:  shutting down
db           | 2026-10-28 19:12:50.864 UTC [75] LOG:  checkpoint starting: shutdown immediate
db           | 2026-10-28 19:12:50.883 UTC [75] LOG:  checkpoint complete: wrote 14 buffers (0.1%); 0 WAL file(s) added, 0 removed, 0 recycled; write=0.001 s, sync=0.013 s, total=0.021 s; sync files=12, longest=0.002 s, average=0.002 s; distance=20 kB, estimate=20 kB; lsn=0/BF044A8, redo lsn=0/BF044A8
db           | 2026-10-28 19:12:50.884 UTC [1] LOG:  database system is shut down
cache        | 1:M 28 Oct 2026 19:12:50.933 * User requested shutdown...
cache        | 1:M 28 Oct 2026 19:12:50.933 * Saving the final RDB snapshot before exiting.
cache        | 1:M 28 Oct 2026 19:12:50.936 * DB saved on disk
cache        | 1:M 28 Oct 2026 19:12:50.936 # Redis is now ready to exit, bye bye...
db           | Container stopped.
db           | Container removed.
cache        | Container stopped.
cache        | Container removed.
journey-test | Removing task network...
journey-test | Task network removed.
journey-test | journey-test finished with exit code 0 in 7.6s.

The only style that shows dependency containers’ stdout/stderr, setup-command output, and full image-build output (Image build | ...) — everything the other styles discard. In exchange, no container is interactive in this mode: the task container gets no TTY and no stdin, and every container gets TERM=dumb (matching Batect — a full-screen program can’t render into line-prefixed output). That is why, next to simple’s capture, npm draws no spinner here.

Nothing in examples/ builds from a Dockerfile (every container uses a prebuilt image), so Image build | ... output has no real capture to point at here.

Colour

Colour in Ratect’s own output (the exit code in the summary line, all’s per-container prefixes, the Error:/Warning: markers, and the bold that picks out task, container and image names and commands in simple and fancy progress) is, by default, emitted only when the stream being written to is a terminal — each stream decides for itself, so with ratect run test > out.txt the progress on stderr is still coloured while a 2>err.txt gets plain text, RUST_LOG lines included — and a task command’s own output is never touched either way. No message depends on its colour to be read: colour only distinguishes one container’s prefix from another’s or emphasises a marker word, a name or the exit code, and Ratect never paints text in the terminal’s own white or black, which some themes render invisible. Three controls adjust that, and their precedence is fixed:

ControlEffect
--no-colorDisables colour in Ratect’s own output, on both streams. Since colour is already skipped when a stream isn’t a terminal, this only matters on an interactive console — unless CLICOLOR_FORCE is also set, which it overrides. Also makes simple, not fancy, the auto-selected style; an explicit -o fancy --no-color still gets a colourless fancy.
NO_COLORIf set — to anything, even empty, per no-color.org — exactly the same effect as --no-color.
CLICOLOR_FORCEIf set to anything other than 0, forces colour even when a stream isn’t a terminal (a CI log viewer that renders ANSI despite the pipe). Never affects which style is auto-selected.

--no-color/NO_COLOR always win: if either is set, CLICOLOR_FORCE is ignored.