<a id="episode-2-quickstart"></a>

# Quickstart guide

## What is the purpose of the quickstart guide?

The purpose of the quickstart guide is to enable a user of ESMValTool to run
ESMValTool as quickly as possible by making the minimum number of changes.

## How do I load and check the ESMValTool environment?

For this quickstart guide, it is assumed that ESMValTool has already been
installed at the site where it will be run. If this is not the case, see the
[Installation](episode_3_installation.html.md) episode in this tutorial.

Load the ESMValTool environment by following the instructions in the
[ESMValTool installation and environment activation guide](../quickstart/installation.html.md#install-on-hpc).
This will typically involving loading a module like so:

```bash
module load esmvaltool
```

Check the ESMValTool environment by accessing the help for ESMValTool:

```bash
esmvaltool --help
```

## How do I configure ESMValTool?

Create the ESMValTool user configuration file. By default, this file is written
to `~/.config/esmvaltool/config-user.yml`:

```bash
esmvaltool config copy defaults/config-user.yml
```

Edit the ESMValTool user configuration file using your favourite text editor to
uncomment the lines relating to the site where ESMValTool will be run.

For more details about the ESMValTool user configuration file, see the
[Configuration](episode_4_configuration.html.md) episode in this tutorial.

## How do I run a recipe?

Run the example Python recipe:

```bash
esmvaltool run examples/recipe_python.yml
```

Wait for the recipe to complete. If the recipe completes successfully, the last
line printed to the screen at the end of the log will look something like:

```bash
YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Run was successful
```

View the output of the recipe by opening the HTML file produced by ESMValTool.
The location of this file is printed to the screen near the end of the log:

```bash
YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Wrote recipe output to:
file:///$HOME/esmvaltool_output/recipe_python_[DATE]_[TIME]/index.html
```

For more details about running recipes, see the
[Running your first recipe](episode_5_recipe.html.md) episode in this tutorial.

## Conclusion

This quickstart guide introduces the minimum steps needed to get ESMValTool
running on your system. Once the environment is loaded, configured, and a recipe
has been run successfully, you are ready to explore the wider tutorial and more
advanced workflows.
