CLI reference
This page reflects the options available in the most recent version of Batect.
If you are not running the most recent version, run ./batect --help to see what options are available in your version.
Run a task
Run a task by running ./batect <task-name>. For example, to run the-task, run ./batect the-task.
Pass additional arguments to a task
You can also pass arguments to the task command by passing those arguments by running ./batect <task-name> -- <args...>.
For example, to run the task the-task with the arguments arg1 arg2, run ./batect the-task -- arg1 arg2.
Shell tab completion
See the shell tab completion section for information on supported shells and installation instructions.
Options
--cache-type: Set cache type to use--clean: Clean up all caches for this project--config-fileor-f: Use a non-standard configuration file name--config-vars-file: Set config variables from a file--config-var: Set a config variable--disable-ports: Disable port binding on the host machine--docker-cert-path,--docker-tls-ca-cert,--docker-tls-certand--docker-tls-key: Customise certificates used to provide authentication to daemon and to verify daemon's identity--docker-config: Path to directory containing Docker client configuration files.--docker-context: Docker CLI context to retrieve Docker daemon connection settings from--docker-host: Use a non-standard Docker host--docker-tlsand--docker-tls-verify: Connect to Docker over TLS--enable-buildkit: Use BuildKit to build images--helpor-h: Get help for Batect's CLI--list-tasksor-T: See a list of available tasks--log-file: Create a debugging log--max-parallelism: Set maximum setup and cleanup operations to run in parallel--no-color: Disable coloured output--no-cleanup,--no-cleanup-after-failureand--no-cleanup-after-success: Disable cleaning up--no-proxy-vars: Disable propagation of proxy-related environment variables--no-update-notification: Disable update notification--no-wrapper-cache-cleanup: Disable wrapper cache cleanup--override-image: Override the image used by a container--outputor-o: Force a particular output style--skip-prerequisites: Skip prerequisites--use-network: Use an existing network for tasks--upgrade: Upgrade Batect--version: Get Batect, Docker and OS version information
--cache-type
By default, Batect will use a Docker volume for each cache for Linux containers. Use this option to instruct Batect to use a different storage mechanism.
Supported values are:
volume: use Docker volumesdirectory: use directories mounted from the project's.batect/cachesdirectory
The BATECT_CACHE_TYPE environment variable can also be used to set the default cache type. If both the environment
variable and the --cache-type option are set, the value given with --cache-type takes precedence.
This option has no effect on Windows containers. Windows containers always use directory mounts for caches.
Example:
./batect --cache-type=directory the-task
--clean
Running ./batect --clean will remove all caches created for this project.
This command respects the value of the --cache-type option and the BATECT_CACHE_TYPE environment variable.
Use --clean-cache to remove specific caches rather than all caches.
--clean-cache
Running ./batect --clean-cache=<cache name> will remove the named cache for this project.
This option can be provided multiple times, for example: ./batect --clean-cache=cache-1 --clean-cache=cache-2 or ./batect --clean-cache=cache-1,cache-2
will both remove the cache-1 and cache-2 caches.
This command respects the value of the --cache-type option and the BATECT_CACHE_TYPE environment variable.
Use --clean to remove all caches.
--config-file or -f
By default, Batect will use a configuration file called batect.yml in the current directory.
Use this option to instruct Batect to use a different file.
Example:
./batect --config-file my-other-config-file.yml the-task
--config-vars-file
By default, Batect will automatically apply values for config variables from the YAML file batect.local.yml
if it exists.
Use --config-vars-file to specify a different file to use instead of batect.local.yml.
Values provided with --config-var take precedence over values provided in any file.
Example:
./batect --config-vars-file batect.ci.yml the-task
Example batect.ci.yml contents:
log_level: debug
user_name: alex
--config-var
Use --config-vars to specify values for an individual config variable.
Values must be in the format <variable name>=<variable value>.
Values provided with --config-var take precedence over values provided in a file (either explicitly with
--config-vars-file or from the default batect.local.yml file)
and default values defined in the configuration file.
Example:
./batect --config-var log_level=debug the-task
--disable-ports
By default, Batect binds ports from containers to the host machine running Batect. These are defined with ports on the container or ports on the task.
However, in some situations, it can be useful to disable these bindings. In particular, when running multiple tasks in parallel, such as on CI systems, host port bindings can result in conflicts.
Passing --disable-ports disables all port bindings for all containers. This includes port bindings defined at the task level.
Example:
./batect --disable-ports the-task
--docker-cert-path, --docker-tls-ca-cert, --docker-tls-cert and --docker-tls-key
If your Docker daemon requires TLS, Batect needs three files in order to connect to it:
- the CA certificate that can be used to verify certificates presented by the Docker daemon (
--docker-tls-ca-cert) - the certificate that can be used to prove your identity to the Docker daemon (
--docker-tls-cert) and corresponding private key (--docker-tls-key)
By default, these files are stored in the Docker client configuration directory and are named ca.pem, cert.pem and key.pem respectively.
You can instruct Batect use a non-default location for any of these files with the options mentioned above, or override the default directory for these
files with --docker-cert-path. If the DOCKER_CERT_PATH environment variable is set, Batect will use that as the default directory, or otherwise
use the value specified with --docker-config / DOCKER_CONFIG.
If both --docker-cert-path (or DOCKER_CERT_PATH) and a path for an individual file is provided, the path for the individual file takes precedence.
These options mirror the behaviour of the docker CLI's --tlscacert, --tlscert and --tlskey options.
These options only apply if the default Docker CLI context is in use. See Docker daemon connection settings
for further explanation.
--docker-config
By default, Batect will look for Docker client configuration files in the directory provided by the DOCKER_CONFIG environment variable,
or ~/.docker if DOCKER_CONFIG is not set. Use this option to instruct Batect to use a different directory.
Example:
./batect --docker-config ~/.my-other-docker-config the-task
--docker-context
The Docker CLI context to retrieve Docker daemon connection settings from.
By default, Batect will use the active context set with docker context use, or the context from the DOCKER_CONTEXT
environment variable.
Example:
./batect --docker-context colima the-task
This option mirrors the behaviour of the docker CLI's --context option.
Other Docker daemon connection options such as --docker-host and --docker-tls only apply if the default Docker CLI context is in use.
See Docker daemon connection settings for further explanation.
--docker-host
By default, Batect will connect to the Docker daemon using the path provided in the DOCKER_HOST environment variable, or
the default path for your operating system if DOCKER_HOST is not set. Use this option to instruct Batect to use a different path.
Example:
./batect --docker-host unix:///var/run/other-docker.sock the-task
This option only applies if the default Docker CLI context is in use. See Docker daemon connection settings
for further explanation.
--docker-tls and --docker-tls-verify
By default, the Docker daemon only accepts plaintext connections from the local machine. If your daemon requires TLS, use the --docker-tls-verify option
to instruct Batect to use TLS. Batect will also automatically enable this option if the DOCKER_TLS_VERIFY environment variable is set to 1.
If your daemon presents a certificate that does not match its hostname, use the --docker-tls option (without --docker-tls-verify) to instruct
Batect to not verify the hostname.
Using --docker-tls without --docker-tls-verify is insecure and should only be used if you understand the implications of this.
These options mirror the behaviour of the docker CLI's --tls and --tlsverify options.
These options only apply if the default Docker CLI context is in use. See Docker daemon connection settings
for further explanation.
--enable-buildkit
Support for BuildKit in Batect is considered experimental. Please file an issue if you encounter any problems.
By default, Batect will use the legacy builder to build Docker images. Docker recently introduced a new image builder, BuildKit, that offers improved performance and some new features.
Use this option to instruct Batect to use BuildKit to build images, rather than the legacy image builder.
Example:
./batect --enable-buildkit the-task
Batect will automatically enable this flag if the DOCKER_BUILDKIT environment variable is set to 1 or true.
Note that BuildKit is only supported on Docker 18.09 or later, or on earlier versions when Docker is running with experimental features enabled.
--help or -h
Running ./batect --help will show a summary of the options available on the command line.
--list-tasks or -T
Batect can produce a short summary of all tasks in the current configuration file along with their
description, and grouped by their group.
For example, ./batect --list-tasks produces output like this:
Build tasks:
- build: Build the application.
Test tasks:
- continuousUnitTest: Run the unit tests in watch mode.
- unitTest: Run the unit tests once.
Utility tasks:
- outdated: Check for outdated dependencies.
- shell: Start a shell in the development environment.
When combined with --output=quiet, Batect produces output suitable for parsing by other applications.
Tasks are listed in alphabetical order, with one task per line. Each task is followed by a tab character, then
its description.
For example, ./batect --list-tasks --output=quiet produces output like this:
build Build the application.
continuousUnitTest Run the unit tests in watch mode.
unitTest Run the unit tests once.
outdated Check for outdated dependencies.
shell Start a shell in the development environment.
--log-file
Use this option to instruct Batect to generate a debugging log at the specified path as it runs. This may be requested if you submit an issue.
If the log file already exists, Batect will append further log messages to the end of the file.
Example:
./batect --log-file /tmp/debugging-log.json the-task
--max-parallelism
By default, Batect will try to run all setup and cleanup steps in parallel, as described in the task lifecycle. On some machines, this can overwhelm the Docker daemon, leading to timeouts and other issues. Use this option to limit the number of setup or cleanup steps to run in parallel.
Note that this does not limit the number of containers that can run in parallel.
Example:
./batect --max-parallelism=4 the-task
--no-color
By default, Batect will produce coloured output if it detects that your console supports it. However, sometimes Batect may incorrectly believe your console supports coloured output, or your console may incorrectly report that it supports coloured output when it does not. (This is a common issue with some CI systems.) This can lead to garbled or difficult to read output.
Passing this flag will disable all coloured output, even if Batect believes your console supports it.
Example:
./batect --no-color the-task
--no-cleanup, --no-cleanup-after-failure and --no-cleanup-after-success
By default, Batect will automatically cleanup all containers and other resources it creates while running a task. However, sometimes it can be useful to leave all the created containers running to diagnose issues running a task.
- Use
--no-cleanup-after-failureto not clean up if any task fails to start for any reason. - Use
--no-cleanup-after-successto not clean up the containers and other resources created for the main task (the one specified on the command line) if it succeeds. - Use
--no-cleanupto enable both of the above.
Example:
./batect --no-cleanup-after-failure the-task
--no-proxy-vars
By default, Batect will automatically propagate proxy-related environment variables as described here. Use this option to disable this behaviour.
Example:
./batect --no-proxy-vars the-task
--no-update-notification
Batect automatically checks for updates at most once every 24 hours and displays a notification if a newer version is available.
Passing this flag will disable both the update check and notification.
This flag is automatically enabled if --output is set to quiet.
--no-wrapper-cache-cleanup
Batect automatically removes old versions of itself that have been downloaded and cached locally if they haven't been used in 30 days.
Passing this flag will disable this cleanup process. You can manually remove these files from ~/.batect/cache yourself at any time.
--override-image
By default, Batect will use the image defined in the configuration file (either with image or build_directory).
Use this option to override the value in the configuration file and use a different image for a specific container.
Values must be in the format <container name>=<image>.
Example:
./batect --override-image build-env=ruby:2.7.0 the-task
--output or -o
Batect offers four styles of output:
fancyis best for interactive use, providing very clean output about the current state of execution and showing output from only the task containerRunning integrationTest... database: container started, waiting for it to become healthy... exchange-rate-service: container started, waiting for it to become healthy... build-env: waiting for dependencies database and exchange-rate-service to be ready...
simpleis best for non-interactive use (eg. on CI), providing a log of what happened and showing output from only the task containerRunning integrationTest... Building database... Pulling ruby:2.5.1... Building exchange-rate-service... Pulled ruby:2.5.1. Built database. Starting database... Started database. Built exchange-rate-service. Starting exchange-rate-service...
alldisplays output from all containersdatabase | database | waiting for server to shut down....2019-09-14 10:14:29.060 UTC [83] LOG: received fast shutdown request database | 2019-09-14 10:14:29.061 UTC [83] LOG: aborting any active transactions database | 2019-09-14 10:14:29.064 UTC [83] LOG: background worker "logical replication launcher" (PID 90) exited with exit code 1 database | 2019-09-14 10:14:29.064 UTC [85] LOG: shutting down database | 2019-09-14 10:14:29.085 UTC [83] LOG: database system is shut down database | done database | server stopped database | database | PostgreSQL init process complete; ready for start up. database | database | 2019-09-14 10:14:29.174 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432 database | 2019-09-14 10:14:29.174 UTC [1] LOG: listening on IPv6 address "::", port 5432 database | 2019-09-14 10:14:29.177 UTC [1] LOG: listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432" database | 2019-09-14 10:14:29.189 UTC [129] LOG: database system was shut down at 2019-09-14 10:14:29 UTC database | 2019-09-14 10:14:29.194 UTC [1] LOG: database system is ready to accept connections exchange-rate-service | info: [http:6000 exchange-rate-service] ::ffff:127.0.0.1:57532 => GET /ping database | Container became healthy. build-env | Running bundle exec rake spec:integration...
quietdisplays only the output from the task and error messages from Batect/usr/local/bin/ruby -I/code/.bundle-cache/gems/rspec-core-3.8.2/lib:/code/.bundle-cache/gems/rspec-support-3.8.2/lib /code/.bundle-cache/gems/rspec-core-3.8.2/exe/rspec --pattern spec/integration/\*\*/\*_spec.rb -I lib -I spec
There are some differences between these output styles to be aware of:
| Output style | fancy | simple | quiet | all |
|---|---|---|---|---|
| Progress information | Detailed (eg. download % completed, health check status) | Basic (eg. image pull started, container ready) | Errors only | Basic (eg. image pull started, container ready) |
| Displays output from | Task container only | Task container only | Task container only | All containers |
| stdin connected (if present) | Yes, to task container only | Yes, to task container only | Yes, to task container only | No |
| TTY connected (if present) | Yes, to task container only | Yes, to task container only | Yes, to task container only | No |
| Image build output shown | Only on build failure | Only on build failure | Only on build failure | Always |
By default, Batect will automatically pick an output style that it believes is appropriate for the environment it is running in -
fancy if it believes your environment supports it, or simple otherwise.
Passing this flag allows you to override what Batect believes is appropriate.
Example:
./batect --output simple the-task
Passing --output=quiet implies --no-update-notification.
Passing --output=quiet also modifies the output of --list-tasks
to make it easier to parse with other applications.
--skip-prerequisites
Normally, Batect will run all tasks defined as prerequisites for the task given on the command line, before then running the requested task.
Use this option to run only the requested task.
Example:
./batect --skip-prerequisites the-task
--tag-image
Batect automatically tags images built for containers with a name based on the project name and container name.
Use --tag-image to add additional tags to the built image. This tag can then be used to then push the image to a remote registry with docker push, or to ensure that subsequent task invocations
use exactly the same image with --override-image.
Values must be in the format <container name>=<image>, for example:
./batect --tag-image build-env=my-build-env:v1.2.3 the-task
Tags can include remote registries, for example:
./batect --tag-image build-env=docker-images.mycompany.com/my-build-env:v1.2.3 the-task
Multiple tags can be applied to the same built image by giving --tag-image multiple times, for example:
./batect --tag-image build-env=my-build-env:v1 --tag-image build-env=my-build-env:v1.2.3 the-task
--tag-image can't be used with containers that pull images directly with image.
--use-network
By default, Batect will create a new Docker network for each task, as described in the task lifecycle. Use this option to provide an existing network to use for all tasks.
Example:
./batect --use-network=my-existing-network the-task
--upgrade
Running ./batect --upgrade will automatically upgrade Batect in the current project to the latest
available version.
--version
Running ./batect --version will show a summary of the versions of Batect, Docker and your operating
system, which can be useful when diagnosing issues with Batect.
Docker daemon connection settings
In order for Batect to communicate with a Docker daemon, it needs two key pieces of information: the host and any TLS-related connection settings.
These settings can come either from the default Docker CLI context, or another context. A context contains all of the information
Batect needs to communicate with a Docker daemon.
Context precedence
Batect follows the same logic as the docker CLI tool when determining which context to use, with scenarios at the top of
the following list having higher precedence:
- If the
--docker-contextoption is provided, that context is used - If the
--docker-hostoption is provided, thedefaultcontext is used - If the
DOCKER_HOSTenvironment variable is set, thedefaultcontext is used - If the
DOCKER_CONTEXTenvironment variable is set, that context is used - If there is an active context previously selected with
docker context use, that context is used - Otherwise, the
defaultcontext is used
default context
The default context is unlike other contexts in that it is dynamic: it respects options set on the command line
or through environment variables, and falls back to Docker's default settings if neither of these sources have been
set.
For example, if the --docker-host option is provided, the default context will use the host from
that option. If the option is not provided, it will use the value of the DOCKER_HOST environment variable if set.
Otherwise, if option is not provided and the environment variable is not set, the default context will fall back to
the default value appropriate for the current operating system (eg. unix:///var/run/docker.sock on macOS and Linux).
Other contexts
Other contexts ignore command line options and environment variables and use only the settings stored in the context.
These settings can be viewed with docker context inspect <name> (eg. docker context inspect colima), and modified
with docker context update.
A list of available contexts can be viewed with docker context ls, and a new context can be created with docker context create.