ratect-compat CLI Reference
ratect-compat [OPTIONS] [TASK_NAME] [-- ADDITIONAL_ARGS...]
This reflects the flags Ratect implements (ratect-compat/src/main.rs) —
every Batect CLI flag is supported, flag-for-flag, unless listed in
differences from Batect.
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, and Two binaries, two
formats for which to pick.
Where options go
Options go before the task name, as in Batect. The first argument that isn’t an
option or an option’s value is the task name, and nothing after it is read as an
option. Only -- and arguments for the task may follow the task name: anything else,
such as ratect-compat build --disable-ports or ratect-compat build extra, is
refused before anything runs, with an error naming the task name and the first extra
argument. Under --list-tasks, --clean, --clean-cache or --upgrade, which
replace the task, whatever follows the options is ignored, so ratect-compat --list-tasks a b lists the tasks.
An option’s value that starts with - has to be given after =, as in
--use-network=-x: given as the next argument, it’s refused — see differences from
Batect.
A path given to -f, --config-vars-file or --log-file is resolved as Batect resolves it: a
leading ~ is your home directory, even where the shell leaves it alone
(--config-file=~/batect.yml), and . and .. are removed before the path is used,
so link/../batect.yml is ./batect.yml whether or not link is a symlink. A leading
.. stays. Before any command runs — --clean included — an -f you give must name
a file, and so must --config-vars-file; a --log-file must name a file or nothing
yet.
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. A value placeholder here, such as <CONTAINER=IMAGE>, describes the
shape of the value; --help prints clap’s own instead, named after the option
(--override-image <OVERRIDE_IMAGE>).
| Flag | Short | Default | Description |
|---|---|---|---|
--config-file <PATH> | -f | batect.yml | Path to the configuration file to load. |
--list-tasks | -T | — | List all tasks defined in the config file, then exit. Doesn’t run anything. |
--help | -h | — | Print help (auto-generated by clap). |
--version | -V | — | Print the Ratect version. |
Configuration variables
| Flag | Short | Default | Description |
|---|---|---|---|
--config-var <NAME=VALUE> | — | — | Sets a config variable’s value; repeatable, once per NAME — a NAME given twice is rejected while the arguments are parsed. Takes precedence over --config-vars-file and the variable’s default. |
--config-vars-file <PATH> | — | batect.local.yml if it exists | A flat YAML file of config variable name: value pairs, in the same format as batect.yml itself. Every value is a string, as in Batect: an unquoted number or boolean is read as written (3.10 is 3.10, not 3.1), and a null or empty value is refused. Lower precedence than --config-var. When not given, defaults to batect.local.yml in the current directory if that file exists (an absent default file just means no overrides from a file, not an error); one that exists but isn’t a file fails every command, as in Batect. Read only when a task runs, as in Batect: every command checks only that a named file is a file, so nothing in it, nor a --config-var naming an undeclared variable, stops --list-tasks. |
Task execution
| Flag | Short | Default | Description |
|---|---|---|---|
--use-network <NAME> | — | — | Reuses an existing Docker network for every task in this invocation instead of creating (and removing) a fresh one per task. Errors clearly if the named network doesn’t exist. See task lifecycle. |
--disable-ports | — | — | Disables publishing of any container’s ports to the host, regardless of what’s configured. |
--no-proxy-vars | — | — | Don’t propagate proxy environment variables (http_proxy, https_proxy, ftp_proxy, no_proxy) to image builds or containers, nor the proxies in Docker’s config.json to image builds — see Proxies. |
--skip-prerequisites | — | — | Don’t run the named task’s own prerequisites. Only ever affects the task actually named on the command line — if that task is itself reached as someone else’s prerequisite in a later invocation, this flag has no bearing on that. |
--override-image <CONTAINER=IMAGE> | — | — | Overrides the image used by CONTAINER; repeatable. Replaces the container’s image/build_directory and image_pull_policy entirely — the override is always pulled under the default IfNotPresent policy, regardless of what the container itself configures. An empty CONTAINER or IMAGE, a CONTAINER given twice, or one also given to --tag-image, is rejected while the arguments are parsed. A CONTAINER the config doesn’t define fails the run once it reaches its first task with a run, before anything of that task starts; a run that reaches no such task, such as --skip-prerequisites on a task with only prerequisites, doesn’t check it. |
--tag-image <CONTAINER=TAG> | — | — | Tags the image built by CONTAINER with TAG, in addition to the default <project_name>-<container_name> tag; repeatable, and CONTAINER may be given more than once to apply multiple tags. Only valid for a container that actually builds an image — errors immediately if CONTAINER is configured to use a pulled image, and errors once the whole task (and its prerequisites) finishes if CONTAINER never actually ran. An empty CONTAINER or TAG, or a TAG that docker tag would refuse, such as _nonsense or one with uppercase in its repository name, is rejected while the arguments are parsed, before anything runs, and so is a CONTAINER also given to --override-image, before the config is loaded. |
--enable-buildkit | — | — | Use BuildKit for image builds, taking precedence over the DOCKER_BUILDKIT environment variable — see config reference. No --disable-buildkit counterpart; force the classic builder via DOCKER_BUILDKIT=0 instead. |
--max-parallelism <N> | — | unbounded | From 1 to 2147483647, as in Batect. Caps how many image pulls/builds, container creates, dependency container starts, and setup-command executions run concurrently across the whole invocation — a create and a start are separate capped steps, and no slot is held while a container waits for its dependencies. Health-check waits, the task’s own container’s run, and container stop/removal are never gated — see Differences from Batect. |
--cache-type <volume|directory> | — | BATECT_CACHE_TYPE, then volume | Storage mechanism for a cache volume mount (see Cache volumes): volume resolves it to a Docker named volume, directory to a host directory under <project_directory>/.batect/caches/<name>/. Has no effect on a config with no cache mounts — but does still select which storage --clean/--clean-cache act on. A BATECT_CACHE_TYPE that is neither volume nor directory, exactly, fails every command unless this flag is given. |
Cleanup after a run
| Flag | Short | Default | Description |
|---|---|---|---|
--no-cleanup | — | — | Equivalent to providing both --no-cleanup-after-failure and --no-cleanup-after-success. |
--no-cleanup-after-failure | — | — | If an infrastructure error occurs (a build/pull/health-check/setup-command failure, or anything else before the task’s own container gets to run — or the task container’s own health check or setup commands failing while its main command is still running, which cancels it), leave every container and network created for the task that failed in place instead of removing them, so the issue can be investigated — a prerequisite’s failure included. A task’s own container exiting non-zero is not “failure” for this purpose — see --no-cleanup-after-success. One divergence from Batect: containers are left genuinely running, not just present-but-stopped — see Differences from Batect. |
--no-cleanup-after-success | — | — | If the named task’s own container runs to completion — regardless of its exit code — leave every container and network created for that task in place instead of removing them. Prerequisites are still cleaned up after success, so only the named task’s resources are kept. Same divergence as --no-cleanup-after-failure: left genuinely running, not stopped-but-present. The exit code is still the task container’s own, where Batect’s is always 255 here — see Differences from Batect. |
Docker connection
Which daemon these reach, their DOCKER_* environment-variable defaults, and
TLS with a private certificate authority are on Connecting to
Docker, shared with ratect. Every invocation
accepts them; they’re used only when it actually connects. --docker-context
beside --docker-host or a TLS option is refused whether or not the invocation
connects, as in Batect.
| Flag | Short | Default | Description |
|---|---|---|---|
--docker-host <HOST> | — | DOCKER_HOST | Docker host to connect to — see Connecting to Docker. |
--docker-context <NAME> | — | DOCKER_CONTEXT, then the active context, unless a host is set | Docker CLI context to connect through — see Connecting to Docker. |
--docker-config <PATH> | — | DOCKER_CONFIG, then ~/.docker | Directory containing the Docker CLI’s own configuration — see Connecting to Docker. |
--docker-tls | — | — | Use TLS, identically to --docker-tls-verify — see Connecting to Docker. |
--docker-tls-verify | — | DOCKER_TLS_VERIFY | Use TLS, verifying the daemon’s certificate — see Connecting to Docker. |
--docker-cert-path <PATH> | — | DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.docker | Directory containing any of ca.pem/cert.pem/key.pem — see Connecting to Docker. |
--docker-tls-ca-cert <PATH> | — | ca.pem in the certificate directory | The TLS CA certificate — see Connecting to Docker. |
--docker-tls-cert <PATH> | — | cert.pem in the certificate directory | The TLS client certificate — see Connecting to Docker. |
--docker-tls-key <PATH> | — | key.pem in the certificate directory | The TLS client key — see Connecting to Docker. |
Cache management
| Flag | Short | Default | Description |
|---|---|---|---|
--clean | — | — | Removes every one of this project’s own cache volumes/directories (per --cache-type or BATECT_CACHE_TYPE) and exits — doesn’t run anything, and never reads the config file, though a --config-file you give must name one. See Cache volumes. |
--clean-cache <NAME> | — | — | Removes just the named caches and exits, instead of every one of them. Takes a comma-separated list of names, each trimmed of surrounding whitespace, and is repeatable. Given together with --clean, the explicit name(s) win — --clean’s own “everything” behavior only applies when --clean-cache is never given at all. |
Output
| Flag | Short | Default | Description |
|---|---|---|---|
--output <STYLE> | -o | auto | fancy, simple, quiet or all; unset auto-selects fancy on an interactive console, simple otherwise — see Output Styles. |
--no-color | — | — | No color in Ratect’s own output (a task’s own output is never affected), and simple becomes the auto-selected style — see Colour for how it combines with NO_COLOR/CLICOLOR_FORCE. |
--log-file <PATH> | — | — | Writes Ratect’s own internal logs to this file, in addition to stderr: Ratect’s own at debug and other crates’ at info, ending with why the run failed when it did — unless RUST_LOG is set, in which case it governs the file too (see Environment variables). Bollard’s debug records, which carry each Docker request’s body, a container’s environment included, reach the file only when RUST_LOG asks for them. Plain text, one record per line, no ANSI color codes; stderr’s own output, colour included, is the same with or without it. |
Recognized, no effect
--upgrade, --no-update-notification, and --no-wrapper-cache-cleanup are accepted
but change nothing Ratect does — hidden from --help, since they’re not real Ratect features, just
recognized so an existing Batect invocation carrying one doesn’t hard-fail outright
(an unrecognized flag is a clap parse error that kills the entire invocation before
anything runs at all, including --list-tasks — unless it comes after --version or
--help, which act as soon as they’re reached). 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. As in Batect, it’s still a command of its own:
it replaces a task name and --clean/--clean-cache, which then don’t run, while
--list-tasks replaces it, which then lists the tasks and prints no notice. 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
The four styles (fancy, simple, quiet, all), their captures and the
auto-selection rule are on Output Styles, shared with
ratect — the rendering is the same code in both binaries.
TLS with a private certificate authority
Why Ratect never skips certificate verification, and the worked example of
running your own CA instead, are on Connecting to
Docker,
shared with ratect.
Positional arguments
| Argument | Description |
|---|---|
TASK_NAME | The name of the task to run, as defined under tasks: in the config file. Required unless --list-tasks, --clean, --clean-cache or --upgrade is given — see Exit codes and error reporting. |
-- ADDITIONAL_ARGS... | Anything after a literal -- is appended as literal argv entries after the task’s own tokenized command — see below. Only applies to the task named on the command line, never to its prerequisites. |
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 neither the task’s run nor its container has a command, ADDITIONAL_ARGS
(when given) replace the image’s default CMD, as plain docker run <image> <args> does; the image’s ENTRYPOINT is kept. So for an image built with
ENTRYPOINT ["server"] and CMD ["--port", "80"], ratect-compat <task> -- --debug runs server --debug, not server --port 80 --debug. With
RUST_LOG=debug, the run logs the CMD the arguments replaced.
Exit codes and error reporting
An invocation is on one of two paths, and its exit code depends on which. A line is a
run unless it has one of the flags that replace a task: --list-tasks/-T,
--clean, --clean-cache or --upgrade. That holds whether or not a task is named and
whether or not the arguments parse; a flag counts only where it would be read as one, not
after -- or as another option’s value. --help and --version exit 0 on either path,
once the arguments reach them. The design is
decisions/0016.
A run — ratect-compat <task> — exits with one of three things, answering one question:
did the task’s own container run to an exit code of its own?
- It did: that exit code,
0included. Ratect waits for the container to exit and inspects its status — a task whose command isexit 42makesratect-compatitself exit42, matchingdocker run’s convention rather than collapsing every failure to one code. A task’s own125,126or127passes through the same way. 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. One exception: if every container exited0but Ratect then fails to clean up — the daemon refuses to remove a container or the task network, or a Ctrl+C stops the cleanup with something still to remove — the run exits125instead, and a prerequisite that fails this way stops the chain there. A task’s own non-zero code is never overridden, and what--no-cleanup,--no-cleanup-after-successor--no-cleanup-after-failureleaves in place on purpose isn’t a cleanup failure — nor is a container or network that something else already removed, such as a dependencydocker rm -f’d mid-run, since nothing is left behind. - A termination signal ended it: 128 + that signal’s own number —
130for Ctrl+C (SIGINT),143forSIGTERM,129forSIGHUP— 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, whatever cleanup does afterwards. All three abandon the run and then clean it up — see Differences from Batect for the full behavior, including what--no-cleanup-after-failuredoes to it and what a second signal does. A signal that arrives only during the cleanup of a run that had already finished ended nothing, so rule 1 applies: a passing run whose cleanup then completes still exits0. One that arrives during a prerequisite’s cleanup ends the run before the next task starts, and exits 128 + its number. One that arrives while the run is still connecting to Docker ends it at once, with nothing yet to clean up, however long the connection would have taken. A run whose stdout reader goes away —ratect-compat test | head -n 1, onceheadhas its line — ends the same way, as thoughSIGPIPEhad ended it: it exits141, after the same cleanup, with a notice on stderr saying the stdout closed. A closed stderr never ends a run. - It never ran, or never finished, for any other reason:
125—docker run’s own code for “thedockercommand itself failed”. An unknown or misused flag (ratect-compat --bogus build, or a bareratect-compat --bogus), no task name, a missing or malformed config file, a--config-vars-filethat isn’t a file, a task or container referenced by name that doesn’t exist, a dependency cycle, an unreachable daemon, an image pull or build that fails, a dependency that exits or never becomes ready, a setup command that fails, a--log-filethat can’t be opened: all125, one code, with the reason on stderr.
Everything other than a run — --list-tasks, --clean, --clean-cache, --upgrade —
runs nothing, so it exits 0 when it succeeds, 1 when it fails (a config that doesn’t
parse under --list-tasks, a --log-file that exists but can’t be opened), and 2 when
it was invoked wrong: a flag that’s rejected (ratect-compat --bogus --clean), or an
option value that fails its own check — a -f or --config-vars-file naming something
that doesn’t exist or isn’t a file, a batect.local.yml that isn’t a file, a BATECT_CACHE_TYPE that is no cache type, a --docker-config, --docker-cert-path,
DOCKER_CONFIG or DOCKER_CERT_PATH naming something that doesn’t exist or isn’t a
directory, --docker-context beside --docker-host or a TLS option, or a --log-file
in a directory that doesn’t exist, or that exists but isn’t a file.
Every failure of Ratect’s own is printed to stderr as Error: <message> (the marker in
bold red when stderr is a terminal) — deliberately not through
tracing::error!/RUST_LOG (which Ratect’s internal diagnostics go 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. Two kinds of failed run print no Error: line,
because something else already reported them: a task’s own non-zero exit (rule 1 — the
exit code, and outside quiet the finished with exit code N summary line, say it,
and the container’s own output says why), and a run ended by a signal or a closed
stdout (rule 2 — the notice said so when it happened). A cleanup failure is reported once, as it
happens, by a line naming what was left behind and the docker command that removes
it. A failure to run a task that has started (an image that won’t pull or build, a
container that can’t be created or started, a dependency that never becomes ready) is
reported once too, when it happens — before the cleanup that follows it, as under
Batect; any failure before a task starts is printed as the process exits.
- Running with no task name, and none of
--list-tasks,--clean,--clean-cacheor--upgrade, is a command-line error, found before the config-variables file or the config is read — so a missing or broken-fstill reports the missing task name. It exits125, like any other usage error on a run, and the error, which points at--list-tasksand--help, is always on stderr, whateverRUST_LOGor-osays. So is-- ADDITIONAL_ARGSwith no task name before it. - A misspelled task name (whether given directly on the command line, or as a
prerequisitesentry) gets aDid you mean 'x'?suggestion appended to the error, for every existing task name within a Levenshtein edit distance of 3 — ported from Batect’s ownTaskSuggester/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 task named on the command line that doesn’t exist ends its error with how to list
the tasks, after any suggestion:
Task 'tst' not found. Did you mean 'test'? (Run 'ratect-compat --list-tasks' for a list of all tasks in this project, or 'ratect-compat --help' for help.), in every output style. A missingprerequisitesentry gets no such hint, as in Batect. - A crash (a genuine bug, not one of the above) exits
101, Rust’s own default for an unhandled panic.ratect-compatprints where to report it (https://github.com/or1can/ratect/issues/new), the binary’s version and platform, and — ifRUST_BACKTRACEisn’t already set — a reminder to re-run with it set, since a backtrace makes a much more useful report.
Environment variables
| Variable | Effect |
|---|---|
RUST_LOG | Controls log verbosity on stderr (error, warn, info [default], debug, trace) — and, if --log-file is given, in the file too, which logs Ratect’s own records at debug when it’s unset. See Filtering RUST_LOG for scoping it to Ratect’s own targets. Unlike Batect, Ratect always logs to stderr regardless of --log-file; Batect’s own default with no --log-file is silent. See Differences from Batect. |
BATECT_CACHE_TYPE | The default for --cache-type: volume or directory, exactly. Any other value, empty included, fails every command but --help and --version, unless --cache-type is given. |
DOCKER_HOST | The default for --docker-host — see Connecting to Docker. |
DOCKER_CONTEXT | The default for --docker-context — see Connecting to Docker. |
DOCKER_CONFIG | The default for --docker-config — see Connecting to Docker. |
DOCKER_CERT_PATH | The default for --docker-cert-path — see Connecting to Docker. |
DOCKER_TLS_VERIFY | The default for --docker-tls-verify — see Connecting to Docker. |
DOCKER_BUILDKIT | Forces the image builder on (1, yes or true) or off (0, no or false), in any case; empty counts as unset, and any other value fails the first build — see --enable-buildkit and config reference. |
NO_COLOR | If set, exactly the same effect as --no-color — see Colour. |
CLICOLOR_FORCE | Forces colored output even when the stream isn’t a terminal, unless --no-color/NO_COLOR is set — see Colour. |
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.