Command-Line Interface¶
Usage¶
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-completions
Install bash tab completion script globally, then exit
Options¶
--cachedir
¶
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
bar
(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
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)
Commands¶
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.
--cache
¶
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 http://foo.com/bar.txt
In this example, the file test.txt
will be copied into the cache directory with a filename corresponding to the URL http://foo.com/bar.txt
. 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.
--dump
¶
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
--dump-path
¶
Prints the absolute path of the loaded yatrfile. For example:
$ yatr -f /path/to/yatrfile.yml --dump-path
/path/to/yatrfile.yml
--install-bash-completions
¶
Installs script for dynamic bash tab completion support. See Installation.
--pull
¶
Downloads all URL includes and imports defined in the loaded yatrfile. If included yatrfiles define URL imports or includes, these will also be downloaded.
--render
¶
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 \
syn>={{version}}
CMD ["python2"]
Suppose one also has the following yatrfile.yml
in the same directory:
macros:
version: 0.0.14
image: foo
tasks:
render: yatr --render -i Dockerfile.j2 -o Dockerfile
build:
- 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 \
syn>=0.0.14
CMD ["python2"]
--validate
¶
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.
--version
¶
Prints the program name and current version to stdout
.