Hello Example


This example illustrates basic Guild configuration.

Project files:

guild.yml Project Guild file
say.py Prints a greeting
cat.py Prints contents of a file
hello.txt Sample file used by hello-file operation



The hello operation prints a message defined by a msg global. It illustrates Guild’s integration with global variables.

hello as defined in guild.yml as follows:

The main attribute indicates that the operation is implemented by the Python say module.

Here’s say.py:

Guild auto-detects that say uses global variables rather than command line arguments. Guild checks for the use of argparse by the module. If the module doesn’t import argparse, Guild assumes that flags are defined as global variables.

To set this explicitly, use flags-dest: globals operation attribute. For example:

  flags-dest: globals
    - msg

The flags-import attribute tells Guild to import only the msg flag. An alternative is to import all flags by specifying either all or yes:

  flags-import: all  # will detect `msg` as the only supported flag

Run hello with default flag values:

guild run hello
You are about to run hello
  msg: Hello Guild!
Continue? (Y/n)

The operation prints the following output:

Hello Guild!

Run with a different flag value:

guild run hello msg="Hello custom flag!"
You are about to run hello
  msg: Hello custom flag!
Continue? (Y/n)

The operation prints:

Hello custom flag!

View information for the latest run using guild runs info. This shows the run metadata including flags.

guild runs info

List files associated with the latest run using guild ls. This list is empty because the operation doesn’t generate files.

guild ls

To view run output use cat with the --output option:

guild cat --output
Hello custom flag!

To view output for the original run:

$ guild cat --output 2

The value 2 indicates that the run with index 2 from guild runs should be used. You can alternatively specify the run ID to ensure you’re viewing output for a particular run.


The hello-file operation prints a message from a file. It illustrates the use of a user-defined file as input to an operation.

Here’s the definition of hello-file:

The operation is implemented in cat.py.

The file flag is used to specify the file used as input to the operation. The file is a dependency and must be configured in the requires operation attribute.

From the example directory, run:

guild run hello-file

You can specify the file to use:

guild run hello-file file=hello.txt

The file requirement is named file to improve the message printed when resolving the resource.

For example:

Resolving file dependency
Using hello.txt for file resource
Reading message from hello.txt
Hello, from a file!


The hello-op operation shows how the result from an operation can be used by another operation.

By convention Guild refers to the required operation as upstream and the requiring operation as downstream.

hello-op requires output from hello-file. In this case, hello-file is the upstream operation and hello-op is the downstream operation.

Here’s the definition of hello-op:

When you run hello-op, Guild looks for a hello-file run. Guild creates links from hello-file in the run directory for the hello-op run.

To use a standard file name for input, the operation renames the upstream file to hello.txt. (This scheme assumes that hello-file contains a single file. If the run happens has more than one file, the first file, sorted in lexicographic ascending order, is renamed and subsequent files are skipped with a warning message.)

By default, Guild selects the latest non-error run for hello-file. You can specify an alternative run using the hello-file resource name:

guild run hello-op hello-file=<run ID>