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 CLI Reference

This documents the ratect binary — the forward-looking CLI, with its own subcommand-based interface. For the compatibility binary, see the ratect-compat CLI reference instead; the two are described separately because they are deliberately different interfaces, not two spellings of one (Two binaries, two formats says which to pick). If you haven’t run a task yet, Getting Started runs a first one end to end, and the worked examples show a real project per language.

Configuration. ratect reads its own native TOML configuration (ratect.toml by default) — see decisions/0003 for why. Its full schema is the ratect.toml reference; it’s the same schema Configuration Reference documents for batect.yml, re-spelled in TOML, with extends in place of YAML anchors, identity in place of run_as_current_user, and native-only additions such as services. A batect.yml is still readable by naming it with -f, so a project can migrate incrementally — ratect config convert translates one automatically.

The native config format

The format itself — the TOML spelling of every field, extends, includes, and the auto-loaded ratect.local.toml — is the ratect.toml reference (the file, local overrides).

Commands

Grouped by purpose. Within a command, the sub-verbs follow their natural workflow order (list before clean/refresh) rather than alphabetically. ratect --help lists the commands in this same order — clap can’t render the group headings there, so the order alone carries them.

Running tasks

CommandWhat it does
ratect run <task> [-- ARGS...]Runs a task. Anything after -- is appended to the task command’s own arguments, or replaces the image’s default CMD when the task has no command.
ratect tasks listLists the tasks this project defines.
ratect services up <group>Brings a service group up, or attaches to it if it already is, shows every member’s output, and takes it down once its exit condition is met — see services options.
ratect services down <group>Takes a service group down, whatever state its containers are in.
ratect services listLists this project’s service groups that have containers or a network on the daemon, in any state.

Managing resources

CommandWhat it does
ratect caches listLists the caches this project can see, project-scoped and shared, with the scope of each.
ratect caches clean [NAME...]Removes this project’s caches, or just the named ones — which may be shared.
ratect includes listLists the cached Git includes shared by every project on this machine.
ratect includes clean [--all]Removes cached Git includes.
ratect includes refreshRe-clones them, picking up a ref that has moved.
ratect resources list [--all]Lists containers and networks left over from task runs that have ended.
ratect resources clean [--all]Removes them.

Configuration & diagnostics

CommandWhat it does
ratect config validateChecks the configuration loads and is problem-free, without a daemon — a CI-friendly gate.
ratect config convertConverts a batect.yml project (read unless -f names another file) into native .toml files, one per file.
ratect doctorChecks this project and this machine for problems, without running anything.

Shell integration

CommandWhat it does
ratect completions <shell>Prints a shell completion script (bash, zsh, fish, powershell, elvish) to stdout — see Shell completion.

There is deliberately no ratect <task> shorthand. ratect-compat takes a task name as a bare positional argument, which works only because it has no subcommands; as ratect grows verbs, “is doctor a task or a command?” becomes a question the interface can’t answer, so run is always explicit.

ratect run build
ratect run test -- --filter integration
ratect tasks list
ratect services up stack
ratect services list
ratect services down stack

ratect caches list
ratect caches clean gradle-cache
ratect includes list
ratect includes refresh
ratect resources list
ratect resources clean --older-than 1d

ratect config validate
ratect doctor

ratect completions zsh

Global options

These work with every command, before or after it — ratect -f custom.yml run build and ratect run build -f custom.yml are the same invocation.

OptionDefaultDescription
-f, --config-file <PATH>ratect.tomlThe configuration file. Parsed by extension — .toml as the native format, .yml/.yaml as Batect-format YAML — so -f batect.yml keeps reading a Batect config while migrating — until it includes a .toml file, which needs a ratect_version only a ratect.toml root can declare. caches uses it only to locate the project directory — it never reads the contents.
-o, --output <STYLE>autofancy, simple, quiet or all; unset auto-selects fancy when stderr is an interactive console, simple otherwise. ratect’s own progress is on stderr in every style; stdout is the task’s own output — see Output Styles.
--no-color—No color in Ratect’s own output (never affects a task’s own output), and simple becomes the auto-selected style — see Colour for how it combines with NO_COLOR/CLICOLOR_FORCE.

Narrower options attach to the commands that actually use them, rather than being global: a flag that’s accepted and then ignored reads as a promise. So the config-variable options below belong to run, services up, config validate and doctor (the commands that evaluate configuration), and the Docker connection options to run, services, caches, resources and doctor (the ones that reach a daemon).

OptionApplies toDescription
--config-var <NAME=VALUE>run, services up, config validate, doctorSets a config variable. Repeatable; wins over --config-vars-file and the variable’s own default.
--config-vars-file <PATH>run, services up, config validate, doctorA file of config variable values (a flat NAME = VALUE map), parsed as TOML or YAML by extension. In a YAML file an unquoted number or boolean is read as written, as in ratect-compat. Defaults to an auto-discovered ratect.local.toml beside the config file, when present.

A path given to -f or --config-vars-file has a leading ~ expanded to your home directory, and . and .. removed before the path is used, so link/../ratect.toml is ./ratect.toml whether or not link is a symlink. A leading .. stays. A --config-vars-file you give must name a file: run refuses one that doesn’t before reading the config, and config validate and doctor report it as a problem.

tasks list still accepts both, deprecated: they have no effect there, since listing tasks evaluates no value, and passing either prints a warning saying so. They’ll be removed in a later release.

Docker connection options

Taken by run, services, caches, resources and doctor — every command that reaches a daemon — and never by tasks list, includes or config, which don’t. Which daemon they reach, their DOCKER_* environment-variable defaults, and TLS with a private certificate authority are on Connecting to Docker, shared with ratect-compat.

OptionDefaultDescription
--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-verifyDOCKER_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.

run options

OptionDefaultDescription
--enable-buildkit—Force BuildKit for image builds, over the daemon’s default and DOCKER_BUILDKIT. Only run and services up build images, so only they take it.
--use-network <NAME>—Reuse an existing Docker network for every task in this invocation instead of creating one per task — see ratect-compat’s description.
--disable-ports—Never bind container ports on the host — see ratect-compat’s description.
--no-proxy-vars—Don’t propagate proxy environment variables to image builds or containers, nor the proxies in Docker’s config.json to image builds — see Proxies.
--skip-prerequisites—Run the task alone, without its prerequisites — see ratect-compat’s description.
--override-image <CONTAINER=IMAGE>—Replace a container’s image. Repeatable — see ratect-compat’s description for what it replaces and when it errors, except that here an empty CONTAINER or IMAGE, or a CONTAINER given twice (the last one wins), isn’t rejected.
--tag-image <CONTAINER=TAG>—Extra tag for an image a container builds. Repeatable — see ratect-compat’s description for when it errors, except that here an empty CONTAINER isn’t rejected.
--no-cleanup, --no-cleanup-after-success, --no-cleanup-after-failure—Leave the task’s containers and network in place, running, after success (the task’s own container ran, whatever its exit code), after failure (something failed before it could), or both. After success that is the named task’s alone — its prerequisites are still cleaned up; after failure it is whichever task failed — see ratect-compat’s description.
--max-parallelism <N>unboundedCap concurrent image pulls/builds, container creates, dependency container starts and setup commands — see ratect-compat’s description.
--cache-type <TYPE>volumevolume or directory — see ratect-compat’s description and cache volumes.

services options

services up <group> brings up the service group’s containers — each member, and whatever it depends on, started as a task’s dependency is — then shows every member’s output on stderr, each line under its container’s name as -o all shows it, until the group’s exit_condition is met. It then takes the group down: every container stopped and removed, each before what it depends on, then its network. It exits with the code the group’s exit_code_from selects, and otherwise as a run does: 125 for Ratect’s own failure, 128 + the signal’s number for a termination signal — see Exit codes. Its output style is always all, the one that shows several containers’ output at once, so -o with any other style is refused.

A group that is up belongs to no services up. It is the containers and network carrying its labels, wherever they came from, so a second services up of the same group never starts another copy. What it does depends on what it finds, the first of these that applies deciding:

  • A container only created or being removed, or a network with no container: another services up or services down is bringing the group up or taking it down, so it waits, saying so once, and looks again. A group left that way — by a services up killed outright while bringing it up, or a take-down that couldn’t remove the network because a task was still running on it — is waited on until you end the wait and run services down.
  • Its network gone, or no member up: it replaces the group, saying Replacing service group 'stack': none of its members is up, or its network is gone., then takes it down and brings it up anew.
  • A member up — running, or paused or restarting: it attaches, saying Service group 'stack' is already up; attaching to it. Ending this takes it down., and from then on shows the output of each of the group’s containers that was running as it attached, and waits for the exit condition. It starts nothing: a member that has already exited stays exited and doesn’t count towards the condition, though exit_code_from = { container = "<member>" } still takes the code that member left.

Two services up started at once end up the same way: one brings the group up and the other waits for it, then attaches. Whichever ends:

  • Its exit condition being met, or a termination signal, takes the group down, whoever brought it up — Ctrl+C in an attached services up stops a group another terminal started. Every other services up attached to it then sees its members stop, and ends, finishing whatever of the take-down is left. A further signal during the take-down force-removes what is left, as it does a task’s cleanup.
  • Killed outright (kill -9, a terminal closed under it), a services up takes nothing down and can’t say so: the group stays up. The next services up attaches to it, saying so, and services down ends it.

The group is labelled with the directory of the configuration file up was given. Every checkout of a project shares its project name, so services up in a second checkout attaches to the group the first brought up, and warns that its containers’ bind mounts point into the first: Attaching to service group 'stack', which was brought up from /work/first, not /work/second: its containers' bind mounts point there.

A container already holding one of the group’s names, <project>..<group>..default..<container>, without the group’s labels stops services up with the daemon’s error; Ratect neither attaches to it nor removes it. A container running when services up attaches is used as it is, and a container the configuration has gained since the group came up is not added: to apply a change to the group’s configuration or images, take the group down first.

A task reaches a group that is up by running on its network, whose name is fixed: ratect run <task> --use-network <project>..<group>..default runs the task’s containers there, where each of the group’s containers answers to its name in the configuration, and leaves the network alone afterwards.

services down <group> stops and removes the group’s containers and network, whatever state they are in — running, stopped, or half brought up. While the configuration declares the group, it stops them as up does, each before what it depends on and with its own stop_signal and stop_grace_period; it needs only the project_name the root configuration file sets, though, so it also takes down a group the configuration no longer declares, or one whose configuration fails to load after the root file parses, stopping its containers all at once. A group that isn’t up is no failure. services list shows each group that has containers or a network on the daemon, whatever their state, with each container’s state and the directory it was brought up from; with -o quiet, each group’s name alone.

resources never selects a service group’s containers or network, whatever their state and whatever its options, and doctor doesn’t count them as leftovers: services down is how a group ends.

OptionApplies toDescription
--config-var, --config-vars-fileupAs for run.
Docker connection optionsup, down, listSee Docker connection options.
--enable-buildkitupAs for run.
--cache-type <TYPE>upAs for run: use the same type as the tasks sharing the group’s caches.

caches options

--cache-type <volume|directory> (default volume) selects which storage to act on, for both list and clean — a cache in one is invisible to the other, so this has to match how the project runs its tasks. Under directory, this project’s caches are host directories under <project>/.batect/caches/<name> and shared ones live at ~/.ratect/caches/<name>; with no home directory there are no shared ones. A .batect/caches or .batect that is a symbolic link is followed, as in Batect, so caches clean removes the cache directories wherever it points — see Cache volumes.

caches never reads the configuration file. A cache belongs to the project directory, so both commands work on a project whose configuration is broken or missing entirely — which is exactly when clearing a cache tends to be what’s needed.

caches list prints each cache under the name a volumes entry gives it, not the Docker volume it’s stored in; that name is what caches clean takes back. Under -o quiet it’s one name per line and nothing else, for scripting — and it prints this project’s caches only, unless --scope shared asks otherwise. What it emits is exactly what a caches clean carrying the same flags would act on, so the output can be piped straight back. Naming a cache that doesn’t exist warns on stderr rather than passing silently, since the likeliest cause is a typo. Under --cache-type directory, caches clean also warns when the project has no .batect/caches directory, and names each entry there that it skips because it is a symbolic link, which is never followed. caches clean reports each cache as it is removed, so a removal that fails, which stops the clean, leaves everything removed before it already reported above the error.

--scope <project|shared> restricts both commands to one kind of cache. A shared cache is one every project on the machine can use, so the listing keeps them apart — a shared cache is not this project’s, and most of the ones shown will belong to other projects. ratect caches list, captured on a terminal in examples/full-stack after a run, while ratect/tests/fixtures/shared-cache.toml’s warm-cache task had created its shared cache:

Caches for this project:
- full-stack-npm-cache

Shared caches on this machine:
- shared-tools

Removing a shared cache always takes --scope shared — whether it is named or not, and whether or not this project has a cache of the same name. A shared cache holds storage every other project on the machine is using, so it is never reached by an unqualified clean. ratect caches clean shared-tools, in the same state:

Error: 'shared-tools' is a shared cache, used by every project on this machine. Re-run with '--scope shared' to remove it.

caches clean with no names therefore sweeps this project’s caches only.

Both scopes are read from storage, not from the configuration — a project cache is found by its batect-cache-<key>- prefix, a shared one by ratect-shared-cache-. That is what keeps these commands working on a project whose configuration is broken. With --scope shared, they never read or create the project’s key file, .batect/caches/key, since only a project cache is named after it.

includes options

The Git include cache under ~/.ratect/incl — where a type: git include is cloned and kept. With no home directory there is no cache, and these find nothing. ratect includes list, captured after the one checked-in project with a Git include had been loaded once into an otherwise empty cache:

1 cached Git include(s), 261.3 KiB on disk:

  https://github.com/batect/hello-world-bundle.git at 0.12.0
    261.3 KiB, last used 0 seconds ago

Unlike caches and resources, this cache is global — one directory shared by every project on this machine, keyed by (repo, ref). So there’s no project scoping, and clean reaches other projects’ includes as well as your own. That matters less than it sounds: everything here is re-cloneable, so the worst case is a fetch.

A command that loads the project and has to clone an include for it prints Cloning <repo> <ref>... on stderr first, and a blank line once the clone has succeeded, in every style but quiet; includes refresh prints neither.

CommandDescription
includes cleanRemoves includes nothing has used for 30 days — the same threshold the automatic sweep applies, done on demand.
includes clean --older-than <AGE>A different threshold (30m, 2h, 7d).
includes clean --allEverything, regardless of age.
includes refreshDiscards every cached clone and fetches it again.

Every form of clean also removes the temporary directories left by clones that were interrupted, once unchanged for 30 days: a more recent one may be a clone still in progress. It removes what an interrupted clean, refresh or ratect-compat sweep left at once: each moves a clone aside before deleting it, so one cut short never leaves part of a clone for a later command to use. The next command that needs the include, or includes refresh, clones it again; until then includes list may still show it, at 0 bytes.

clean and refresh carry on past an include they can’t remove, or clone again, and then print an Error: on stderr for each, naming it and why, in every style, and exit 1. A refresh whose clone fails leaves that include removed: the next command that needs it clones it again.

clean names each leftover it removes by its path, after the includes, and counts the leftovers on the total line only when it removed some. One it can’t remove is an Error: and exit 1, as an include it can’t remove is. Here ratect includes clean --all, run with HOME pointed at a scratch directory holding three leftovers and no includes, one of them made unremovable by a read-only subdirectory, removes two and prints an error for the third:

Removed /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.tmp-736f329f71b94dbbb8b10d25461379b0, left by an interrupted clone.
Removed /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.del-bbb06d33962b4e77a2971e0d462b9a1c, left by an interrupted removal.
Removed 0 cached Git include(s) and 2 leftover(s) of interrupted clones and removals.
Error: Could not clean /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.tmp-fda60e700d77468b937c8fd7de2bc4cf, left by an interrupted clone: Permission denied (os error 13)

Under -o quiet only the error is printed. refresh leaves leftovers to clean. Removing part of what an interrupted clone left counts as changing it, so once the cause of an error like this is fixed, clean leaves the rest for another 30 days.

refresh is how you pick up a moved ref. A (repo, ref) pair is cloned once and then never re-fetched, so if ref is a branch — or a tag someone re-pushed — your project keeps using whatever it pointed at the first time, indefinitely. The automatic sweep doesn’t help, because it removes entries that go unused, and an include you’re actively using never becomes stale. Pinning ref to something immutable remains the better answer; refresh is for when it isn’t.

Under -o quiet, list prints repo<TAB>ref<TAB>key per line and nothing else, where key is the entry’s directory under ~/.ratect/incl. In every style, credentials in a repo URL are shown as ***, as everywhere Ratect names one — and so is anything else between its :// and last @, so https://host/a@b shows as https://***@b. Two entries can then look alike only if their remotes differ in nothing but what was hidden, so in the other styles an entry with part of its repo hidden is also named by the first 12 characters of its key: https://***@host/repo.git at v1 (key 45de9a2d81c0).

resources options

Containers and networks outlive a run when something goes wrong — a crash, a kill -9, a --no-cleanup run, or a cleanup that failed. resources finds them by the labels Ratect stamps on everything it creates, so they’re identifiable however long ago they were made. ratect resources list, captured in examples/full-stack after ratect run journey-test --no-cleanup-after-success:

6 left over from 1 previous run:

  journey-test (7 seconds ago, run 11ac2452-81ed-412f-9dd5-3115c03563a9):
    - container db (running)
    - container cache (running)
    - container app (running)
    - container journey-test (exited)
    - container ratect-health-check-app (exited)
    - network ratect-full-stack-network-u4f9aa

Remove them with: ratect resources clean

Grouped by run, because that’s the unit a leftover belongs to: a run that was killed outright, or crashed, leaves a network and every container it started, and they only make sense together. (Ctrl+C, SIGTERM and SIGHUP aren’t those cases any more — each cleans up after itself. SIGKILL can’t be trapped by anything, so it still is; see Differences from Batect.) A container is named as your configuration names it, not by the <project>-<container>-<suffix> name it has in Docker — or, for the companion an external_health_check runs, by the ratect-health-check-<container> name Ratect gives it.

OptionApplies toDescription
--alllist, cleanTask runs Ratect can’t tell have ended, as well as those it can. Never a task run still going.
--all-projectslist, cleanEvery Ratect project’s leftovers, not just this one’s — never anything Ratect didn’t create. Also the way to use resources from outside a project directory, since the project scope is read from the configuration.
--older-than <AGE>list, cleanOnly task runs older than AGE — 90s, 30m, 2h, 7d. A task run’s age is its oldest container’s or network’s.

resources list is clean’s dry run. Both take the same options and select identically, so whatever list shows you is exactly what clean with those same options will remove — there’s no separate --dry-run because there’s nothing for it to do differently.

A task run still going is never selected. A task run carries the same labels whether it is going or left over, so each one holds a lock for as long as its process drives it, cleanup included — both binaries take it — and resources reads it. The kernel frees a lock when its process ends, however it ends, kill -9 included. Each task run is one of three things:

A task run isWhenSelected
endedits lock is free, and was written on this machine since it last bootedby default
still goingits lock is heldnever
unknownRatect can’t tell: there is no lock, it was written before a reboot or by another kernel (Ratect in a container sharing your home), or the lock can’t be read, as on some network filesystemswith --all

A task run’s containers and network are selected or left out together, and one selected by --all is listed as one Ratect can't tell it has ended. A task run is unknown in particular when it was left by a Ratect too old to take the lock, so a leftover from before an upgrade needs --all. So does every leftover once the machine has rebooted, though it has certainly ended. --older-than is the guard for those: resources clean --all --older-than 1d. On any platform but Linux and macOS, Windows included, every task run is unknown.

When the selection leaves task runs out for their state, both commands say so on stderr — Left out 2 task runs still going, and 1 task run Ratect can't tell has ended (pass --all to include it). A task run too young for --older-than isn’t counted there. Containers and networks carrying Ratect’s project label but no task run’s are neither selected nor counted, and nor is a service instance’s container whose image or configured labels gave it a task run’s label.

--all here composes with --older-than, where includes clean’ --all conflicts with it: that one means every cached include, whatever its age, while this one means every state a leftover can be in short of still going. Neither is --all-projects, which widens the scope to every project, not the states.

Each lock is a file, ~/.ratect/runs/<run>.lock, named for the task run’s id. A task run that cleaned up fully deletes its own, and clean deletes an ended task run’s once it has removed everything of it. Nothing else does: one kept by a task run that, cut short, stopped waiting for the daemon to answer a create (it may have made something), one left by a task run whose leftovers went another way (docker rm, or ratect-compat alone), or from before a reboot, stays, a few dozen bytes each. Delete them by hand only when nothing is running and nothing is left over, on this daemon or any other the home directory is used with: deleting a leftover’s file makes it unknown.

Under -o quiet, list prints resource ids one per line and nothing else, ready to pipe into docker rm. Removal takes containers before networks, since a network still holding an endpoint can’t be removed; a resource that fails to remove doesn’t stop the rest, but clean then exits 1 with one Error: naming each refusal.

resources reads one thing from the configuration — the root file’s project_name, to scope itself to this project — and nothing else in it, so neither the ratect_version check nor a value this machine can’t evaluate gets in the way. What to remove comes from the labels alone.

Nothing without Ratect’s own labels is ever listed or removed, --all-projects included: containers started by other tools, and Docker’s built-in bridge/host/ none networks, are invisible to both commands.

What this doesn’t cover: cache volumes/directories are caches’ territory, not resources’ — they’re a deliberate cache, not a leftover. Likewise the Git include cache under ~/.ratect/incl is includes’ own command. Built images are tagged <project>-<container> and reused/overwritten on every run rather than tracked as a resource — also a deliberate cache. Tmpfs mounts and exec instances die with their container, so there’s nothing left to find.

config

ratect config validate is doctor’s configuration half on its own — it loads the config, evaluates every container and task against this machine, and runs the same config-only checks (values this machine can’t evaluate, a build_directory/Dockerfile a build can’t use, an absolute dockerfile, floating image tags, dependencies with no health_check, an entry given more than once in one dependencies or prerequisites list, a mount above an identity home), exiting non-zero on a problem. It never touches Docker, so it’s the gate to run in CI when all you want to know is “is the config valid?”, without a daemon. It takes the same --config-var/--config-vars-file options as run, and reads ratect.local.toml the same way, since evaluating the config can need them. A config that doesn’t load stops at its first error.

ratect config convert migrates a Batect-format batect.yml project to the native format. It reads batect.yml unless -f names another file: -f’s usual ratect.toml default is the file it writes, not the one it reads.

ratect config convert          # writes ratect.toml beside it, and a .toml beside each include
ratect config convert --stdout  # prints instead, to review or pipe

It’s one-directional (ratect-compat stays YAML; the reverse would be lossy) and converts each file the project owns beside itself: the root becomes ratect.toml, and every local included file, at any depth, becomes a .toml with the same name in its own directory (more/c.yml → more/c.toml ), with each include entry rewritten to point at the converted file. Nothing is re-based — every value is copied exactly as written — so a relative path in more/c.toml resolves against more/, exactly as it did in more/c.yml (see Where relative paths resolve). A Git include stays a Git include, its repo, ref, path and allow_host_paths carried across: nothing from a bundle is copied out, and no file in one is converted. A root batect.yml with no project_name converts to a ratect.toml naming the project as ratect-compat does — after the root file’s directory — since ratect.toml requires one. Nothing is written if any converted file already exists — the error lists them all; pass --force to overwrite them, or --stdout to print instead. With more than one file, --stdout prints each document in order, the root first, each under a # === … === banner naming its file (more/c.toml ).

The conversion preserves each file’s configuration, not formatting: YAML anchors/aliases/merge keys are expanded inline and comments are dropped — so each output carries a header and is a starting point to review, not a blind drop-in. Before anything is written, every conversion is checked to round-trip losslessly back to the same configuration, so each file encodes the configuration you started with — and every way ratect runs that configuration differently is listed, as below.

A task’s own container has no readiness gate, so its health check — from health_check or from its image’s own HEALTHCHECK — isn’t waited on, and its setup_commands don’t run (see Dependency Readiness). An image’s HEALTHCHECK can’t be seen without the image, so check those yourself. An enabled run_as_current_user becomes identity, which doesn’t replace the image’s identity files, and applies --user and changes a cache volume’s owner only on a rootful Linux daemon, and a disabled one is dropped (what changes). Its home_directory is used as written in a batect.yml but evaluated as identity.home in a ratect.toml, so one containing a $ or < expression changes value, and one holding a .. is refused until that is changed. Likewise, a string-form volumes entry’s host path is used as written in a batect.yml but evaluated in a ratect.toml. A \ in either stays a backslash (foo\bar becomes foo\\bar), since a batect.yml never reads one as an escape, so a $ or < after one is still converted as an expression, and listed. One that would then be no valid expression — img$, a $ with no name after it — can’t have meant one, so convert escapes it whole (img\$) and it keeps its value, unlisted. An image is always escaped whole: a batect.yml refuses an expression there, so nothing in one was meant as one. Two more concern a Git include. A pathless entry whose bundle also offers a ratect-bundle.toml would have ratect load that file instead of the batect-bundle.yml the batect.yml loaded, so convert sets its path to batect-bundle.yml and says so; remove path to switch to the native file. And a bundle declaring Git includes of its own is refused by ratect unless allow_nested_git_includes is set on that entry (see Nested Git includes) — a grant convert never writes for you.

config convert lists each place in the converted project where one of these applies — per converted file, its include entries’ items first, then its containers’ in order of container name — after converting, and again in that file’s own header, so the list travels with the file. ratect -f batect.yml config convert --stdout, captured in ratect/tests/fixtures/convert — a project with something to check:

# Generated by `ratect config convert` from batect.yml.
# Review before use: comments were not carried over.
#
# Check before use:
# Task 'test' runs container 'app' as its own, so under ratect the container's 'setup_commands' don't run — a task's own container has no readiness gate (see https://github.com/or1can/ratect/blob/main/docs/dependency-readiness.md#the-tasks-own-container).
# Container 'app' has a volume host path '$HOME/.cache', which batect.yml uses as written but ratect evaluates as an expression — check what it resolves to under ratect.

ratect_version = "0.13.0"
project_name = "convert-fixture"

[containers.app]
image = "alpine:3.18.2"

[[containers.app.setup_commands]]
command = "./warm-cache.sh"

[[containers.app.volumes]]
container = "/cache"
local = "$HOME/.cache"

[tasks.test]
description = "Runs the tests"

[tasks.test.run]
command = "./run-tests.sh"
container = "app"
Check before using ratect.toml:
  warning Task 'test' runs container 'app' as its own, so under ratect the container's 'setup_commands' don't run — a task's own container has no readiness gate (see https://github.com/or1can/ratect/blob/main/docs/dependency-readiness.md#the-tasks-own-container).
  warning Container 'app' has a volume host path '$HOME/.cache', which batect.yml uses as written but ratect evaluates as an expression — check what it resolves to under ratect.

With --stdout, the documents are all that reaches stdout; each heading and its list after it are on stderr. Without it, they follow the success message on stdout, naming the file written. With nothing to check, neither the list nor the header block appears. Either way the conversion succeeds and exits 0, and the list prints whatever RUST_LOG is set to, under -o quiet too.

The result declares the converting binary’s own version as its ratect_version. It writes each volumes, ports and devices entry as an object, the only form the native schema admits, whichever form batect.yml used.

doctor

Answers “why did that fail?”, or “will it?”, without running a task. ratect doctor, captured in ratect/tests/fixtures/doctor — a project written to trip each warning and a problem — after ratect run build --no-cleanup-after-success there:

Checking ratect.toml...
  ok      Docker daemon reachable (29.8.2)
  ok      Docker daemon class: desktop
  warning 'batect' is a Batect wrapper script and still runs Batect, not Ratect — delete it and run ratect (or ratect-compat) from your PATH
  ok      ratect.toml loads (6 container(s), 2 task(s))
  warning Container 'deploy': cannot evaluate 'environment.TOKEN' ('$DEPLOY_TOKEN'): Host environment variable 'DEPLOY_TOKEN' is not set, and no default was given (e.g. '${DEPLOY_TOKEN:-default}') — a run that reaches it fails on this machine
  warning container 'database' uses a floating image tag — pin it, or the same configuration will run a different image later
  warning dependency 'cache' has no health_check — unless its image defines one, it counts as ready the moment it starts
  warning container 'app' gives 'cache' more than once in its 'dependencies' — it starts only once
  problem container 'app': build_directory '/private/tmp/ratect/ratect/tests/fixtures/doctor/missing-dir' doesn't exist
  warning container 'scratch' has identity.home '/work/me' under the writable bind mount at '/work' — a home that doesn't exist yet is created on the host, in that directory
  warning 1 task run(s) left over from previous runs — see `ratect resources list`

11 check(s): 1 problem(s), 7 warning(s).
Error: 1 problem(s) found.

The Docker daemon class line says which kind of daemon this connection reached: rootless or userns-remap when the daemon reports it, desktop when Ratect runs on macOS or Windows and reaches it over a local socket, and rootful Linux otherwise. A daemon reached over the network is classified by what it reports, so it is never desktop. Docker Desktop on Linux is rootful Linux, deliberately: only vendor-specific signals tell it from a native daemon (why), and identity treats it as one. If the daemon answers but its class can’t be read, that is a warning.

The class also decides two warnings a run gives too, about containers in the project, whichever task reaches them, leaving out a base with no image or build_directory, which nothing can run:

  • identity on a userns-remap daemon. Every container user maps to a subordinate host uid, root included, so the container has only other users’ access to a bind mount the host user owns, and what it does write has a subordinate owner. That ownership has to be arranged on the host. Its home is still guaranteed.
  • A non-root user on a rootless or userns-remap daemon. The container has only other users’ access to a bind mount the host user owns, so it usually can’t write there or read anything private. A user of 0 or root isn’t reported.

Neither stops a run, and a run reaching such a container warns about it too. doctor can’t report the third thing a run warns about, an identity container whose image runs it as a non-root user on either daemon: the image’s user isn’t in the configuration, the image may not be local, and doctor doesn’t pull it. config validate reports none of these, since it doesn’t connect to a daemon.

On a rootful Linux daemon, doctor also warns about each writable bind mount of a container that writes there as root, whose files may end up root-owned on the host, and suggests identity, or run_as_current_user for a container in a .yml file, which can’t set identity. That is a container with no identity, no enabled run_as_current_user, and either no user or a user of 0 or root. With no user it assumes root, since it doesn’t pull the image to find out. It fires on Docker Desktop on Linux too, where the files are in fact the host user’s, because that file sharing is what the class can’t see. identity is still sound there. A mounted socket or single file isn’t reported, since a write can’t change its owner, except from a daemon reached over the network, whose paths aren’t on this machine to look at. It says nothing when you are root, since root-owned files are then yours. A run doesn’t warn about this, and neither does config validate.

Over a local socket to a rootful Linux daemon, doctor also reads who owns each writable bind mount’s host path, for a container that runs as you: one with identity, or an enabled run_as_current_user. If another uid owns it, it warns that a write there may be refused, as it can be for a directory an earlier run left root-owned. “May”, since group or other permissions can still allow it, and on Docker Desktop on Linux a bind mount looks like the container user’s own, so the write may well succeed. A missing path isn’t reported, since a run tries to create it as you, and nor is one whose owner can’t be read, or anything when you are root. A daemon reached over the network isn’t checked, because its mounts are on its own filesystem, and neither is any other class, where the container doesn’t run as your uid. It’s a warning, and config validate doesn’t report it.

A problem will fail a run — an unreachable daemon, a configuration that doesn’t load, a build_directory or Dockerfile a build can’t use. A warning works but is likely to bite: a floating image tag (latest, or no tag at all) means the same configuration runs a different image next week, an absolute dockerfile only works where the project is checked out at that path, and a dependency with no health_check counts as ready the moment it starts unless its image defines one, which is where “connection refused” on the first run comes from.

So is each value this machine can’t evaluate — an unset $VAR, a <var with no value — naming its container or task, its field and the expression, as deploy’s $DEPLOY_TOKEN above. Every one is reported, not only the first. It’s a warning rather than a problem because a variable only CI sets is expected to be missing on a laptop, and it fails only a run that reaches it: ratect run build there never evaluates deploy. The same goes for a value that evaluates but can’t be used — an expression-valued identity.home that isn’t an absolute path, or a Git-included container’s host path that evaluates to somewhere outside its boundary. A container with such a value is left out of the checks that read its values, so its image tag and build_directory aren’t judged until it evaluates. When everything evaluates, doctor says so on its own ok line.

A dependencies or prerequisites list that gives the same entry twice is a warning, as app’s cache above. Batect refuses such a file; Ratect loads it and starts or runs the entry once, so the repeat is reported rather than refused. Entries are compared as written: a wildcard prerequisite given twice is a repeat, but a wildcard beside a task it matches is not.

A mount above a container’s identity home is reported for what it does to that home, which is created through the mount before the container starts. The deepest mount strictly above the home decides, with a bind mount or cache going over a tmpfs at the same path, and a mount at the home itself supplies it, so that gets no finding whatever is above it:

Deepest mount above the homeFinding
tmpfsProblem: the run fails, whether or not the home already exists
Read-only bind mount or cacheWarning: the run fails unless the home already exists there
Writable bind mountWarning: a missing home is created on the host, in that directory
Writable cacheNone

A tmpfs higher up changes nothing, since a deeper mount goes on top of it when the container starts. A cache under --cache-type=directory, a host directory, is judged as a volume, since neither doctor nor config validate takes that flag. Only the configuration’s mounts are read, so a VOLUME the image declares between a tmpfs and the home gets the tmpfs’s problem, though the home is created in that volume and the run works.

If you’re migrating from Batect, doctor also flags a leftover batect/batect.cmd wrapper script. Those aren’t harmless: ./batect still downloads and runs the unmaintained JVM binary, so you can think you’ve switched to Ratect while ./batect quietly runs the old tool.

Delete the wrapper and run ratect (or ratect-compat, for strict Batect compatibility) from your PATH. Batect’s committed wrapper was its installer — it fetched the right JVM version on demand — whereas Ratect is an ordinary binary you install once, so there’s nothing for a committed wrapper to do. (Don’t repoint the wrapper at Ratect by symlinking it: a committed symlink is machine-specific and doesn’t work for batect.cmd on Windows, and it still needs the binary on the PATH anyway.)

The one exception is a codebase with ./batect hardcoded across CI jobs, Makefiles and docs that you can’t change all at once: there, replacing the wrapper with a one-line transitional shim — exec ratect-compat "$@" — keeps those call sites working while you migrate them (it still needs ratect-compat on the PATH). A wrapper that no longer runs Batect isn’t flagged.

doctor exits non-zero if it found any problem, and zero for warnings alone, so it works as a CI step. Under -o quiet it prints only warnings and problems.

The environment checks run even when the configuration itself won’t load — “your config is broken and your daemon isn’t running” is more useful than fixing one to discover the other. It also reports leftovers unprompted, since the whole reason resources exists is that nobody thinks to look: a warning counting the leftover task runs that have ended, which is what a bare resources clean removes, and another counting those Ratect can’t tell have ended, pointing at resources list --all. A task run still going isn’t reported.

Shell completion

ratect completions <shell> prints a completion registration script to stdout for bash, zsh, fish, powershell or elvish. Source it from your shell’s startup file:

# bash — in ~/.bashrc
source <(ratect completions bash)

# zsh — in ~/.zshrc, *after* compinit has run (see the note below)
source <(ratect completions zsh)

# fish — in ~/.config/fish/config.fish
ratect completions fish | source

zsh needs its completion system initialized first. The zsh script ends with a compdef call, and compdef only exists once compinit has run — so the source line must come after autoload -U compinit && compinit in your ~/.zshrc (frameworks like oh-my-zsh already run compinit for you; just keep the source line after they load). Sourcing it in a bare shell that hasn’t run compinit fails with command not found: compdef; run autoload -U compinit && compinit first to try it interactively. bash and fish need no such initialization.

It completes command and flag names, their fixed values (-o fancy|simple|…, --cache-type volume|directory), file-path arguments, and — the part that earns its keep on a task runner — task names: ratect run <TAB> lists the tasks your config defines. That last one is dynamic: the installed script re-invokes ratect at completion time to read the config, always without cloning, pulling, or touching Docker, so a <TAB> is instant and safe.

Task completion honours an explicit -f, and follows the config’s includes — local files, and Git includes that are already cached. It never clones or pulls, so tasks from a Git include that hasn’t been fetched yet won’t appear until the first real run caches it.

Built on an unstable API. Task-name completion uses clap’s unstable-dynamic engine, so it may occasionally need a fix as that API settles. The static parts (commands, flags, values, paths) don’t depend on it.

Exit codes and diagnostics

Identical to ratect-compat’s: both binaries share one mapping, whose design is decisions/0016. An invocation is on one of two paths, and its exit code depends on which. ratect run is a run, even when its arguments don’t parse, and so is ratect services up; every other verb isn’t. For a line that doesn’t parse, the subcommand counts where it would be read as one — not after --, and not as another option’s value — so ratect --bogus run test is a run. --help and --version exit 0 on either path, once the arguments reach them.

ratect services up is a run too, whose exit code is the one its group’s exit_code_from selects in place of the task’s own (see services options); the rules below hold for it with that change.

A run 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. A task’s own 125, 126 or 127 passes through the same way, and a prerequisite that fails this way stops the chain. One exception: if every container exited 0 but Ratect then fails to clean up — a removal the daemon refused, or a cleanup stopped with Ctrl+C with something still to remove — the run exits 125 instead, and a prerequisite whose cleanup fails stops the chain there. A task’s own non-zero code is never overridden. A container or network that something else already removed, such as a dependency docker rm -f’d mid-run, isn’t a cleanup failure, 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. Any of the three abandons the run and then cleans up after it; a second one during that cleanup force-removes whatever is left, a Ctrl+C after that stops the cleanup, and ratect resources list finds whatever that leaves (for services up, ratect services down <group> removes it instead). A signal that arrives only during the cleanup of a run that had already finished doesn’t change its exit code; one during a prerequisite’s cleanup ends the run before the next task starts; one while the run is still connecting to Docker ends it at once, with nothing yet to clean up. A run whose stdout reader goes away — ratect run test | head -n 1, once head has its line — ends the same way, as though SIGPIPE had ended it: 141, after the same cleanup. A closed stderr never ends a run.
  3. It never ran, or never finished, for any other reason: 125 — an unknown or misused flag (ratect run --bogus, ratect -o bogus run test), a config file that isn’t there, a config that doesn’t load, an unknown task, an unreachable daemon, a failed pull or build, a dependency that never became ready. An unknown task’s error ends with how to list the tasks: (Run 'ratect tasks list' for a list of all tasks in this project, or 'ratect run --help' for help.).

Every other verb runs nothing, so it exits 0 when it succeeds; 1 when it fails (config validate on a file that doesn’t parse, caches list with the daemon down, doctor finding a problem); and 2 when it was invoked wrong — a flag that’s rejected (ratect --bogus, ratect tasks list --bogus, a missing subcommand), or an option value that fails its own check, such as a -f naming no file (ratect tasks list where there is no ratect.toml) or a --docker-config naming no directory. doctor and config validate report a -f naming no file as a problem they found instead, and exit 1, as doctor does a Docker directory that isn’t one; a flag rejected in their own arguments is still 2.

Every failure of Ratect’s own reaches stderr as Error: <message>, in every output style including quiet, whatever RUST_LOG says. 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 code itself and, outside quiet, the finished with exit code N summary line), and a run ended by a signal or a closed stdout (rule 2 — the notice saying so). A failure to run a task that has started is reported when it happens, before cleanup; one before any task starts, as ratect exits. ratect-compat’s section has each rule in full.

  • RUST_LOG controls Ratect’s own internal logging (default info, on stderr — see Filtering RUST_LOG). Unlike ratect-compat there’s no --log-file; redirect stderr if you want one.
  • A crash (a genuine bug) exits 101 and prints where to report it, ratect’s version and platform, and a reminder to re-run with RUST_BACKTRACE=1 if it isn’t already set — see ratect-compat’s own note on this, which applies identically here.

Differences from ratect-compat

ratect-compatratect
Run a taskratect-compat <task>ratect run <task>
List tasksratect-compat --list-tasksratect tasks list
Cache cleanup--clean/--clean-cacheratect caches clean [NAME...]
Listing cachesnot availableratect caches list
Finding leftovers from a previous runnot availableratect resources list/clean
Bringing a group of containers up togethernot availableratect services up/down/list
Checking a project without running itnot availableratect doctor
Managing the Git include cachenot available (only the automatic sweep)ratect includes list/clean/refresh
Batect-inert flags (--upgrade, --no-update-notification, --no-wrapper-cache-cleanup)accepted, no effectnot offered
--log-filesupportednot offered
Configurationbatect.ymlnative ratect.toml (with extends); batect.yml still readable via -f