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

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>).

FlagShortDefaultDescription
--config-file <PATH>-fbatect.ymlPath 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

FlagShortDefaultDescription
--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 existsA 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

FlagShortDefaultDescription
--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>—unboundedFrom 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 volumeStorage 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

FlagShortDefaultDescription
--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.

FlagShortDefaultDescription
--docker-host <HOST>—DOCKER_HOSTDocker host to connect to — see Connecting to Docker.
--docker-context <NAME>—DOCKER_CONTEXT, then the active context, unless a host is setDocker CLI context to connect through — see Connecting to Docker.
--docker-config <PATH>—DOCKER_CONFIG, then ~/.dockerDirectory 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_VERIFYUse TLS, verifying the daemon’s certificate — see Connecting to Docker.
--docker-cert-path <PATH>—DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.dockerDirectory containing any of ca.pem/cert.pem/key.pem — see Connecting to Docker.
--docker-tls-ca-cert <PATH>—ca.pem in the certificate directoryThe TLS CA certificate — see Connecting to Docker.
--docker-tls-cert <PATH>—cert.pem in the certificate directoryThe TLS client certificate — see Connecting to Docker.
--docker-tls-key <PATH>—key.pem in the certificate directoryThe TLS client key — see Connecting to Docker.

Cache management

FlagShortDefaultDescription
--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

FlagShortDefaultDescription
--output <STYLE>-oautofancy, 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

ArgumentDescription
TASK_NAMEThe 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?

  1. It did: that exit code, 0 included. Ratect waits for the container to exit and inspects its status — a task whose command is exit 42 makes ratect-compat itself exit 42, matching docker run’s convention rather than collapsing every failure to one code. A task’s own 125, 126 or 127 passes 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 exited 0 but 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 exits 125 instead, 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-success or --no-cleanup-after-failure leaves in place on purpose isn’t a cleanup failure — nor is a container or network that something else already removed, such as a dependency docker rm -f’d mid-run, since nothing is left behind.
  2. A termination signal ended it: 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, 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-failure does 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 exits 0. 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, once head has its line — ends the same way, as though SIGPIPE had ended it: it exits 141, after the same cleanup, with a notice on stderr saying the stdout closed. A closed stderr never ends a run.
  3. It never ran, or never finished, for any other reason: 125 — docker run’s own code for “the docker command itself failed”. An unknown or misused flag (ratect-compat --bogus build, or a bare ratect-compat --bogus), no task name, a missing or malformed config file, a --config-vars-file that 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-file that can’t be opened: all 125, 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-cache or --upgrade, is a command-line error, found before the config-variables file or the config is read — so a missing or broken -f still reports the missing task name. It exits 125, like any other usage error on a run, and the error, which points at --list-tasks and --help, is always on stderr, whatever RUST_LOG or -o says. So is -- ADDITIONAL_ARGS with no task name before it.
  • 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 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 missing prerequisites entry 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-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

VariableEffect
RUST_LOGControls 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_TYPEThe 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_HOSTThe default for --docker-host — see Connecting to Docker.
DOCKER_CONTEXTThe default for --docker-context — see Connecting to Docker.
DOCKER_CONFIGThe default for --docker-config — see Connecting to Docker.
DOCKER_CERT_PATHThe default for --docker-cert-path — see Connecting to Docker.
DOCKER_TLS_VERIFYThe default for --docker-tls-verify — see Connecting to Docker.
DOCKER_BUILDKITForces 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_COLORIf set, exactly the same effect as --no-color — see Colour.
CLICOLOR_FORCEForces 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.