Skip to content

CLI reference

Note

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.

Shell tab completion

See the shell tab completion section for information on supported shells and installation instructions.

Run a task

Run a task by running ./batect <task-name>. For example, to run the-task, run ./batect the-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.

Set config variables from a file (--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.

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

Set a config variable (--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

Override the image used by a container (--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

Disable cleaning up (--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-failure to not clean up if any task fails to start for any reason.
  • Use --no-cleanup-after-success to 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-cleanup to enable both of the above.

Example:

./batect --no-cleanup-after-failure the-task

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

Skip prerequisites (--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

Disable port binding on the host machine (--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

Use an existing network for tasks (--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

Limit parallelism (--max-parallelism)

By default, batect will try to run all setup and cleanup steps in parallel. On some machines, this can lead 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

See a list of available tasks (--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.

Cleanup all caches for this project (--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.

Upgrade batect (--upgrade)

Running ./batect --upgrade will automatically upgrade batect in the current project to the latest available version.

Get help for batect's CLI (--help)

Running ./batect --help will show a summary of the options available on the command line.

Get batect, Docker and OS version information (--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.

Common options

Use a non-standard configuration file name (--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

Customise cache storage mechanism (--cache-type)

By default, batect will use a Docker volume for each cache mount for Linux containers. Use this option to instruct batect to use a different storage mechanism.

Supported values are:

  • volume: use Docker volumes
  • directory: use directories mounted from the project's .batect/caches directory

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.

Info

This option has no effect on Windows containers. Windows containers always use directory mounts for caches.

Example:

./batect --cache-type=directory the-task

Set cache initialisation image (--linux-cache-init-image)

batect uses an image to initialise cache volumes before they are mounted. Use this option to override the default image. This is useful if you have cached the initialisation image on a local registry.

The BATECT_LINUX_CACHE_INIT_IMAGE environment variable can also be used to set the default initialisation image. If both the environment variable and the --linux-cache-init-image option are set, the value given with --linux-cache-init-image takes precedence.

Example:

./batect --linux-cache-init-image=my.registry.com/batect-cache-init-image:abcd1234 the-task

Customise Docker options

Use BuildKit to build images (--enable-buildkit)

Warning

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.

Use a non-standard Docker host (--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

Connect to Docker over TLS (--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.

Warning

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.

Customise certificates used to provide authentication to daemon and to verify daemon's identity (--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 ~/.docker 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.

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.

Create a debugging log (--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

Disable coloured output (--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

Disable update notification (--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.

Disable wrapper cache cleanup (--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.

Force a particular output style (--output or -o)

batect offers four styles of output:

  • fancy is best for interactive use, providing very clean output about the current state of execution and showing output from only the task container

  • simple is best for non-interactive use (eg. on CI), providing a log of what happened and showing output from only the task container

  • all displays output from all containers

  • quiet displays only the output from the task and error messages from batect

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.

Telemetry options

batect can collect telemetry information to help inform the design and prioritisation of new features and bug fixes.

When batect starts for the first time, it prompts for permission to collect this information and stores this permission.

These options allow you to enable or disable telemetry permanently or for a single invocation:

Disable telemetry permanently (--permanently-disable-telemetry)

If you would like to opt-out of telemetry, run ./batect --permanently-disable-telemetry to disable collecting telemetry data and remove any data that has been collected but not yet uploaded.

This also resets your telemetry user ID, ensuring that if you do ever re-enable telemetry, any previous data uploaded is not associated with any new data.

Enable telemetry permanently (--permanently-enable-telemetry)

If you would like to opt-in to telemetry, run ./batect --permanently-enable-telemetry to enable collecting telemetry data.

Disable telemetry for this invocation (--no-telemetry)

By default, batect uses the permission you granted it when it ran for the first time.

If you would like to disable telemetry collection or uploading for a single invocation, pass the --no-telemetry flag, for example:

./batect --no-telemetry the-task

Note that this does not cause any data that has been collected from other invocations but not uploaded to be removed - it will be uploaded the next time batect runs without the --no-telemetry flag.

You can also set the BATECT_ENABLE_TELEMETRY environment variable to false to disable telemetry collection and uploading.

General notes

  • All command line options that take a value can be provided in --option=value or --option value format.