CLI Reference

ratect-compat [OPTIONS] [TASK_NAME] [-- ADDITIONAL_ARGS...]

This reflects the flags Ratect actually implements today (ratect-compat/src/main.rs), not the full Batect CLI — see differences from Batect for what’s missing.

This is the ratect-compat binary, whose interface deliberately matches Batect’s. The forward-looking ratect binary has its own, subcommand-based interface — see the ratect CLI reference.

Options

Grouped by purpose, matching ratect-compat --help. The grouping is presentational only — every flag parses the same regardless of the section it’s listed under.

Configuration variables

Task execution

Cleanup after a run

Docker connection

Cache management

Output

Recognized for Batect compatibility, no effect

--upgrade, --no-update-notification, and --no-wrapper-cache-cleanup are accepted but do nothing — hidden from --help, since they’re not real Ratect features, just recognized so an existing Batect invocation carrying one doesn’t hard-fail outright (before these were recognized, any of them caused a clap parse error that killed the entire invocation before anything ran at all, including --list-tasks). All three only make sense for Batect’s own self-updating wrapper script, which Ratect — a single native binary — doesn’t have and isn’t planning to grow. --upgrade specifically prints a one-line notice to stderr and exits 0 rather than running silently, since a user invoking it is likely expecting some visible response; reinstall or rebuild Ratect to get a newer version instead. The other two have no wrapper-cache/update notification to disable in the first place, so they’re silently accepted with no message at all.

Output styles

--output/-o controls how Ratect reports its own progress on stdout — never what the task’s command itself prints, which always streams through unmodified. The styles are Batect’s own four, all implemented:

• fancy — a live status block, one line per container in the task’s dependency graph (<name>: <what it's doing right now> — pulling/building with live progress detail, waiting for dependencies, starting, waiting to become healthy, running setup commands, ready), repainted in place as events arrive. There is no spinner — the animation is purely rewriting changed lines, exactly like Batect. The moment the task’s own container starts, the block freezes behind a blank line and the container’s raw output streams below it untouched; after it exits, a single live Cleaning up: ... countdown line tracks teardown, then makes way for the final summary line. Lines are clipped to the terminal’s current width. Requires an interactive console — an explicit -o fancy without one fails up front with a clear error (Batect instead accepts it and crashes on the first repaint). Works with --no-color (the repaint stays; bold/color go — a combination Batect rejects).
• simple — plain, append-only milestone lines: Running <task>..., Pulling <image>.../Pulled <image>., Building <container>.../Built <container>., dependency start/health/setup-command milestones, a blank line + Cleaning up..., and a final <task> finished with exit code <n> in <duration>. summary (the exit code green/red on a color-capable console). No live-updating progress detail at all — safe for CI logs and redirected output. The health/setup-command milestones are shown for dependency containers only: the task’s own container’s 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 — use all (below) to see them. A readiness failure is still reported, on stderr, in every style.
• quiet — no milestone lines at all: stdout is exactly the containers’ own output, so it’s safe to pipe (error reporting stays on stderr, unchanged). Also switches --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.
• all — every line of output prefixed with the container it belongs to (name | , padded to a common column, each container’s prefix in its own color), interleaved as it happens. The only style that shows dependency containers’ stdout/stderr, setup-command output (Setup command N | ...), 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). Task-level lines (the Running <task>... preamble, Cleaning up..., the summary) carry the task’s own name as their prefix.

When --output isn’t given, Ratect auto-selects: fancy on an interactive console (stdout a real terminal, TERM set and not dumb, terminal size queryable, no --no-color); simple otherwise. quiet and all are never auto-selected.

TLS with a private certificate authority

--docker-tls/--docker-tls-verify always fully verify the Docker daemon’s certificate — there is no flag or environment variable that skips verification, unlike Batect’s own bare --docker-tls (which sets Go’s tls.Config.InsecureSkipVerify, disabling chain-of-trust, expiry, and hostname checks all at once, not just the hostname check). This isn’t just inherited from a missing feature: rustls, the library Ratect’s TLS support is built on, takes the same position deliberately — there’s no boolean toggle for skipping verification in rustls either, only a dangerous() accessor that requires implementing the ServerCertVerifier trait from scratch to bypass it. Ratect doesn’t reach for that. If you’ve historically reached for --docker-tls (skip-verify) because your daemon’s certificate is self-signed — including for local development or CI — the fix isn’t to skip verification, it’s to make the certificate verifiable: run your own certificate authority, and trust that, rather than trusting nothing.

The daemon side of this (configuring dockerd to require TLS, generating its server certificate) is standard Docker documentation, not Ratect-specific — see Protect the Docker daemon socket. What follows is the client side: a self-contained, worked example of generating a private root CA, signing a server certificate for the daemon with it, and pointing Ratect at the result.

1. Create a root CA. This is the one certificate you’ll trust from now on — keep ca-key.pem private; it’s the only thing standing between “verified” and “not”.

   openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
     -keyout ca-key.pem -out ca.pem -subj "/CN=my-docker-ca"
   

2. Generate and sign the daemon’s own certificate, naming every hostname/IP clients will actually connect through as a Subject Alternative Name (SAN) — verification checks this, not the certificate’s CN:

   openssl req -newkey rsa:4096 -sha256 -nodes \
     -keyout server-key.pem -out server-req.pem -subj "/CN=docker-daemon"
   openssl x509 -req -in server-req.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
     -out server-cert.pem -days 3650 -sha256 \
     -extfile <(printf "subjectAltName=DNS:docker-daemon.example.com,IP:203.0.113.10")
   

3. Configure dockerd to require TLS with this certificate (/etc/docker/daemon.json or the equivalent dockerd flags — see the Docker documentation linked above), using ca.pem/server-cert.pem/server-key.pem from steps 1–2.

4. Point Ratect at the CA (client certificate/key are only needed if the daemon itself also requires client auth — generate a second cert signed by the same CA for that, following step 2’s pattern):

   ratect-compat --docker-host tcp://docker-daemon.example.com:2376 \
     --docker-tls-verify \
     --docker-tls-ca-cert ./ca.pem \
     test
   

   Or set --docker-cert-path to a directory containing ca.pem (and cert.pem/key.pem, if the daemon requires client auth) instead of naming each file individually — see Options.

If verification fails, the error names the problem (expired, wrong host, untrusted issuer) rather than silently connecting anyway — that’s the entire point of not supporting skip-verify. Regenerate whichever certificate is actually at fault, rather than reaching for a flag Ratect doesn’t have.

Positional arguments

Examples

# List tasks defined in ./batect.yml
ratect-compat --list-tasks

# Run a task from ./batect.yml
ratect-compat test

# Use a config file in a different location
ratect-compat -f ./ci/batect.yml build

# Pass extra arguments through to the task's command
ratect-compat test -- --verbose some/specific/file.rs

# Set a config variable referenced via `<name`/`<{name}` in `environment`
ratect-compat --config-var environment_name=staging test

# Load config variable values from a file instead
ratect-compat --config-vars-file ./ci/config-vars.yml test

Using ADDITIONAL_ARGS in a task command

run.command is tokenized into literal argv (quote/backslash-aware whitespace splitting, no shell involved — matching Batect’s own tokenizer exactly), and anything after -- is appended as further literal argv entries — no special syntax needed in command itself to receive them:

tasks:
  test:
    run:
      container: build-env
      command: cargo test

Running ratect-compat test -- --nocapture here runs cargo test --nocapture inside the container. Args are appended as literal argv entries (never concatenated into the command string and re-parsed), so they’re safe even if they contain characters that would be shell metacharacters elsewhere, like ;, &&, or backticks — Ratect never passes command/ADDITIONAL_ARGS through a shell at all.

If the task’s container has no command at all, ADDITIONAL_ARGS (when given) are passed directly as the container’s entrypoint arguments instead, matching plain docker run <image> <args>.

Exit codes and error reporting

Ratect uses a plain 0 (success) / non-zero (failure) convention, but note the current actual behavior — it doesn’t yet distinguish “nothing to do” from “success”:

• Running with no task name at all (and not --list-tasks) currently exits 0 — Ratect logs a warning but doesn’t fail the process. This is a rough edge, not intentional design; don’t rely on it in scripts.
• A missing or malformed config file (fails to parse), a task/container referenced by name that doesn’t exist, or a dependency cycle all cause a non-zero (1) exit. The error is printed to stderr as Error: <message> — deliberately not through tracing::error!/RUST_LOG (which every other diagnostic goes through — see how it works): a fatal error is the reason the process is about to exit non-zero, not an optional diagnostic, so it stays visible even under RUST_LOG=off or a filter that excludes Ratect’s own target — including under -o quiet, whose whole contract is “only error messages”.
• A misspelled task name (whether given directly on the command line, or as a prerequisites entry) gets a Did you mean 'x'? suggestion appended to the error, for every existing task name within a Levenshtein edit distance of 3 — ported from Batect’s own TaskSuggester/EditDistanceCalculator (confirmed by reading Batect’s source). Multiple equally-close matches are all suggested, e.g. Did you mean 'build' or 'bulid'? — Batect’s own implementation can silently drop one of two equally-close suggestions (its sorting comparator doubles as its de-duplication key), which Ratect’s deliberately doesn’t replicate.
• A run ended by a signal exits 128 + that signal’s own number — 130 for Ctrl+C (SIGINT), 143 for SIGTERM, 129 for SIGHUP — the shell’s own convention, so a script or CI job can tell a cancelled run apart from a failed one and tell what cancelled it. All three abandon the run and then clean it up — see Differences from Batect for the full behavior, including what --no-cleanup-after-failure does to it and what a second signal does.
• A failing command inside the container fails the ratect process too, with the same exit code. Ratect waits for the container to exit and inspects its status — a task whose command is exit 42 makes ratect itself exit 42, matching docker run’s convention rather than collapsing every failure to a generic 1. A task that runs as a prerequisite and fails this way stops the rest of the chain immediately — no other prerequisites, and not the task that depended on it, will run — matching Batect’s documented behavior.
• A crash (a genuine bug, not one of the above) exits 101, Rust’s own default for an unhandled panic. ratect-compat prints where to report it (https://github.com/or1can/ratect/issues/new), the binary’s version and platform, and — if RUST_BACKTRACE isn’t already set — a reminder to re-run with it set, since a backtrace makes a much more useful report.

Environment variables

Ratect supports interpolating host environment variables and config variables into environment values, volume host paths, build_directory, build_args, build_secrets’ path, and a build_ssh entry’s paths in batect.yml ($VAR, ${VAR:-default}, <name — see config reference) — see differences from Batect.