Command-Line Interface


usage: yatr [-h] [-f <yatrfile>] [-i <file>] [-o <file>] [-m <macro>=<value>]
            [-s <setting>=<value>] [--cache-dir <DIR>] [-v] [-p] [--cache]
            [--dump] [--dump-path] [--pull] [--render] [--version]
            [--validate] [--install-bash-completions]
            [<task>] [ARGS [ARGS ...]]

Yet Another Task Runner.

positional arguments:
  <task>                The task to run
  ARGS                  Additional arguments for the task

optional arguments:
  -h, --help            show this help message and exit
  -f <yatrfile>, --yatrfile <yatrfile>
                        The yatrfile to load
  -i <file>             Input file
  -o <file>             Output file
  -m <macro>=<value>, --macro <macro>=<value>
                        Set/override macro with specified value
  -s <setting>=<value>, --setting <setting>=<value>
                        Set/override setting with specified value
  --cache-dir <DIR>     Path of cache directory
  -v, --verbose         Print commands to be run
  -p, --preview         Preview commands to be run without running them
                        (implies -v)
  --cache               Cache local input file (-i) as if it were a URL (-o)
  --dump                Dump macro values and exit
  --dump-path           Print yatrfile path and exit
  --pull                Download all URL includes and imports, then exit
  --render              Use macros to render a Jinja2 template file (requires
                        -i and -o)
  --version             Print version info and exit
  --validate            Validate the yatrfile and exit
                        Install bash tab completion script globally, then exit



Certain yatr features make use of a cache directory to increase the efficiency of repeated yatr invocations. The cache directory is currently used for processing yatrfiles included via URL (see include), extension modules included via URL (see import), as well as for populating bash tab completion values. By default, the cache directory is set to ~/.yatr/, but this may be changed like so:

$ yatr --cache-dir /path/to/cache/dir <some task or command>

-f (--yatrfile)

Specify the yatrfile to load. If this option is not supplied, yatr will try to load a file whose filename matches the regular expression ^[Yy]atrfile(.yml)?$. If such a file is not present in the current working directory, yatr will search rootward up the filesystem tree looking for a file that matches the expression. This is intended as a feature of convenience, so that tasks can be easily executed when working in a project sub-directory. If it is unclear which yatrfile has been loaded, yatr --dump-path may be run to disambiguate.

-i and -o

The -i and -o options specify input and output files, respectively. These options have no effect when invoking yatr to run a task, and are only used by specific yatr commands that require them, such as --render.

-m (--macro)

Macro values may also be set or overridden at the command line by supplying the -m (or --macro) option. For example:

$ yatr -f C.yml -m a=zab --macro d=jkl --dump
a = zab
b = ghi
c = xyz
d = jkl

(See C.yml)

-s (--setting)

Any setting value may be set or overridden at the command line by supplying the -s (or --setting) option. For example:

$ yatr -f D.yml -s silent=false foo

(See D.yml)

-v and -p

If the -v option is supplied at the command line, yatr will print the commands to be run before running them:

$ yatr -v bar foo
echo bar
echo bar baz foo
bar baz foo

If the -p option is supplied, yatr will simply print the commands without running them:

$ yatr -p bar foo
echo bar
echo bar baz foo

(See main example)


As its name implies, yatr is primarily a task runner. As such, its default execution behavior is to run tasks defined in a yatrfile. However, when using a task runner in real-world applications, there are often situations where other execution behaviors become desirable. For example, if it becomes necessary to debug a particular yatrfile, dumping the values of the macros (via yatr --dump) might prove helpful. As such, yatr supports a number of special execution behaviors, called “commands”, which do not run tasks. To avoid unnecessarily restricting the set of potential task names, all yatr commands are prefixed by --. However, unlike normal command-line options, at most one command should be specified at the command line for any yatr invocation.

The following table lists the available commands:

Name Description
--cache Cache local input file (-i) as if it were a URL (-o)
--dump Dump macro values to stdout
--dump-path Print yatrfile path to stdout
--install-bash-completions Install bash tab completion script in /etc/bash_completions.d/
--pull Download all URL includes and imports defined in yatrfile
--render Use macros to render a Jinja2 template file (requires -i and -o)
--validate Validate the yatrfile
--version Print version information to stdout

A discussion of each command is provided below.


Saves a local file specified by -i to the cache directory, as if it had been downloaded from a URL specified by -o. For example:

$ yatr --cache -i test.txt -o

In this example, the file test.txt will be copied into the cache directory with a filename corresponding to the URL This command can be useful in yatrfile development, allowing one to test included functionality without having to upload the included yatrfile(s) every time a change is made.


Prints macro values (including capture values) to stdout. For example, with C.yml, running --dump produces the following:

$ yatr -f C.yml --dump
a = baz
b = ghi
c = xyz


Prints the absolute path of the loaded yatrfile. For example:

$ yatr -f /path/to/yatrfile.yml --dump-path


Installs script for dynamic bash tab completion support. See Installation.


Downloads all URL includes and imports defined in the loaded yatrfile. If included yatrfiles define URL imports or includes, these will also be downloaded.


The --render command renders a Jinja2 template file using the macros defined by a yatrfile. For example, suppose one has the following template for a Dockerfile named Dockerfile.j2:

# -*- dockerfile -*-
FROM python:2-alpine

RUN pip install -U --no-cache \

CMD ["python2"]

Suppose one also has the following yatrfile.yml in the same directory:

  version: 0.0.14
  image: foo

  render: yatr --render -i Dockerfile.j2 -o Dockerfile
    - render
    - "docker build -t {{image}}:latest ."

One could then run:

$ yatr build

to generate the desired Dockerfile and then build the desired Docker image. The generated Dockerfile would look like:

# -*- dockerfile -*-
FROM python:2-alpine

RUN pip install -U --no-cache \

CMD ["python2"]


Validates the loaded yatrfile. A number of validation tasks are performed during the course of loading a yatrfile (such as validating proper YAML syntax) even if the --validate command is not given. However, the --validate command validates further aspects of the loaded task environment, such as ensuring that no task definitions contain undefined macros. If an error is found, an exception will be raised and the program will terminate with a non-zero exit status.


Prints the program name and current version to stdout.