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.
ratectreads its own native TOML configuration (ratect.tomlby default) — see decisions/0003 for why. Its full schema is theratect.tomlreference; it’s the same schema Configuration Reference documents forbatect.yml, re-spelled in TOML, withextendsin place of YAML anchors,identityin place ofrun_as_current_user, and native-only additions such asservices. Abatect.ymlis still readable by naming it with-f, so a project can migrate incrementally —ratect config converttranslates 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
| Command | What 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 list | Lists 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 list | Lists this project’s service groups that have containers or a network on the daemon, in any state. |
Managing resources
| Command | What it does |
|---|---|
ratect caches list | Lists 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 list | Lists the cached Git includes shared by every project on this machine. |
ratect includes clean [--all] | Removes cached Git includes. |
ratect includes refresh | Re-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
| Command | What it does |
|---|---|
ratect config validate | Checks the configuration loads and is problem-free, without a daemon — a CI-friendly gate. |
ratect config convert | Converts a batect.yml project (read unless -f names another file) into native .toml files, one per file. |
ratect doctor | Checks this project and this machine for problems, without running anything. |
Shell integration
| Command | What 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.
| Option | Default | Description |
|---|---|---|
-f, --config-file <PATH> | ratect.toml | The 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> | auto | fancy, 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).
| Option | Applies to | Description |
|---|---|---|
--config-var <NAME=VALUE> | run, services up, config validate, doctor | Sets a config variable. Repeatable; wins over --config-vars-file and the variable’s own default. |
--config-vars-file <PATH> | run, services up, config validate, doctor | A 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.
| Option | 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. |
run options
| Option | Default | Description |
|---|---|---|
--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> | unbounded | Cap concurrent image pulls/builds, container creates, dependency container starts and setup commands — see ratect-compat’s description. |
--cache-type <TYPE> | volume | volume 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 uporservices downis bringing the group up or taking it down, so it waits, saying so once, and looks again. A group left that way — by aservices upkilled 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 runservices 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, thoughexit_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 upstops a group another terminal started. Every otherservices upattached 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), aservices uptakes nothing down and can’t say so: the group stays up. The nextservices upattaches to it, saying so, andservices downends 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.
| Option | Applies to | Description |
|---|---|---|
--config-var, --config-vars-file | up | As for run. |
| Docker connection options | up, down, list | See Docker connection options. |
--enable-buildkit | up | As for run. |
--cache-type <TYPE> | up | As 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.
| Command | Description |
|---|---|
includes clean | Removes 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 --all | Everything, regardless of age. |
includes refresh | Discards 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.
| Option | Applies to | Description |
|---|---|---|
--all | list, clean | Task runs Ratect can’t tell have ended, as well as those it can. Never a task run still going. |
--all-projects | list, clean | Every 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, clean | Only 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 is | When | Selected |
|---|---|---|
| ended | its lock is free, and was written on this machine since it last booted | by default |
| still going | its lock is held | never |
| unknown | Ratect 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 filesystems | with --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:
identityon 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
useron 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. Auserof0orrootisn’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 home | Finding |
|---|---|
tmpfs | Problem: the run fails, whether or not the home already exists |
Read-only bind mount or cache | Warning: the run fails unless the home already exists there |
| Writable bind mount | Warning: a missing home is created on the host, in that directory |
Writable cache | None |
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
compdefcall, andcompdefonly exists oncecompinithas run — so thesourceline must come afterautoload -U compinit && compinitin your~/.zshrc(frameworks like oh-my-zsh already runcompinitfor you; just keep thesourceline after they load). Sourcing it in a bare shell that hasn’t runcompinitfails withcommand not found: compdef; runautoload -U compinit && compinitfirst 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-dynamicengine, 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?
- It did: that exit code,
0included. A task’s own125,126or127passes through the same way, and a prerequisite that fails this way stops the chain. One exception: if every container exited0but 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 exits125instead, 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 dependencydocker rm -f’d mid-run, isn’t a cleanup failure, since nothing is left behind. - A termination signal ended it: 128 + that signal’s own number —
130for Ctrl+C (SIGINT),143forSIGTERM,129forSIGHUP. 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, andratect resources listfinds whatever that leaves (forservices 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, onceheadhas its line — ends the same way, as thoughSIGPIPEhad ended it:141, after the same cleanup. A closed stderr never ends a run. - 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_LOGcontrols Ratect’s own internal logging (defaultinfo, on stderr — see FilteringRUST_LOG). Unlikeratect-compatthere’s no--log-file; redirect stderr if you want one.- A crash (a genuine bug) exits
101and prints where to report it,ratect’s version and platform, and a reminder to re-run withRUST_BACKTRACE=1if it isn’t already set — seeratect-compat’s own note on this, which applies identically here.
Differences from ratect-compat
ratect-compat | ratect | |
|---|---|---|
| Run a task | ratect-compat <task> | ratect run <task> |
| List tasks | ratect-compat --list-tasks | ratect tasks list |
| Cache cleanup | --clean/--clean-cache | ratect caches clean [NAME...] |
| Listing caches | not available | ratect caches list |
| Finding leftovers from a previous run | not available | ratect resources list/clean |
| Bringing a group of containers up together | not available | ratect services up/down/list |
| Checking a project without running it | not available | ratect doctor |
| Managing the Git include cache | not available (only the automatic sweep) | ratect includes list/clean/refresh |
Batect-inert flags (--upgrade, --no-update-notification, --no-wrapper-cache-cleanup) | accepted, no effect | not offered |
--log-file | supported | not offered |
| Configuration | batect.yml | native ratect.toml (with extends); batect.yml still readable via -f |