This guide provides a quick tour of run management functions.
This guide is a continuation of Guild AI Quick Start. Complete that guide before proceeding below.
A script to test runs
guild‑start directory, create a file named
Verify that your project structure is:
- train.py (created in Quick Start - not used in this guide)
To start a run, use the run command.
guild run echo.py
Enter to accept the default message and run the operation. The
script prints the greeting:
By default, Guild prompts you before starting the operation. You can
bypass this prompt by including
‑‑yes as a command line
guild run echo.py -y
echo.py supports a single flag:
msg, which it prints to the
console. You can list supported flags for a script by specifying the
‑‑help‑op option to the
guild run echo.py --help-op
Usage: guild run [OPTIONS] echo.py [FLAG]... Use 'guild run --help' for a list of options. Flags: msg (default is Hello Guild!)
We can run the script with a different value for
guild run echo.py msg='Yo Guild!'
You are about to run echo.py msg: Yo Guild! Continue? (Y/n)
Enter to continue. The script prints the alternate greeting:
While this is a very simple example — certainly not related to machine learning — it demonstrates that Guild runs your Python script unmodified and captures the result as a unique experiment. Later we see what Guild tracks for these operations.
By default, Guild lets a script run to completion, regardless of how long it takes to complete.
You can stop an operation early by typing
Ctrl‑C in the command run
You can alternatively stop a run from a different console by running:
This stops all running operations. You can alternatively specify specific runs to stop. For more information, see the stop command.
List the latest 20 runs:
List all runs by providing the
‑‑all command line option:
guild runs --all
You can filter runs using a variety of options. For example, to show
all runs with a status of
completed, use the
command line option:
guild runs --completed
Guild shows runs with a 1-based index, which may be in commands that accept runs as arguments.
For a list of filter options, see the runs command.
Show run info
If you want information about a run, use runs info:
guild runs info
id: be12ef24483d11e98c3ec85b764bbf34 operation: echo.py status: completed started: 2019-03-16 17:49:23 stopped: 2019-03-16 17:49:23 marked: no label: run_dir: ~/.guild/runs/be12ef24483d11e98c3ec85b764bbf34 command: /usr/bin/python -um guild.op_main echo --msg "Yo Guild!" exit_status: 0 pid: flags: msg: Yo Guild!
By default, Guild shows information for the latest run. You can specify a different run as either an index or a run ID. For example, to show information for the second to last run:
guild runs info 2
You can request additional information by specifying various command line options:
- Files associated with the run (
- Run output (
- Process environment (
- Scalars (
- Dependencies (
- Source code (
For more information, see the runs info command.
List run files
Show files associated with a run using the ls command:
By default, Guild shows files associated with the latest run. You can specify a different run using a run index or run ID.
Show text files
echo.py writes the value of the msg flag to a file named
You can display the contents of a file using the cat command:
guild cat message.txt
To show the contents of
message.txt for the previous run:
guild cat message.txt 2
Guild supports diffing information across runs. For example, to diff
message.txt across the last two runs, use:
guild diff --path message.txt
For more information, see the diff command.
Open run files
Use the open command to open a run directory in your system file browser:
By default, Guild opens the latest run directory.
You can open specific files using the
‑‑path command line
guild open --path message.txt
You can browse the source code associated with a run by specifying the
‑‑source command line option:
guild open --source
Delete runs using runs delete or the alias
By default, Guild deletes all runs. You can specify one or more runs to delete using these forms:
- run index
- run index range
- run ID
Run index ranges are in the form
START:STOP and will select all runs
starts with index
START up to and including the run with index
You can specify status filters such as
For example, to delete the last run, use:
guild runs rm 1
You are about to delete the following runs: [c654363a] echo.py 2019-03-16 18:18:14 completed Delete 1 run(s)? (Y/n)
By default, Guild prompt before deleting runs. You can bypass this
prompt by specifying the
‑‑yes command line option.
Deleted runs can be restored later using runs restore. See below for details.
To delete all failed runs — i.e. runs with status
guild runs rm ‑‑error or the short version
runs rm ‑E.
Restore deleted runs
Deleted runs can be restored using runs restore. By default, Guild restores all deleted runs. You can specify specific runs using indexes or run IDs. For example, to restore the last deleted run, use:
guild runs restore 1
To show deleted runs — i.e. runs that can be restored —
guild runs ‑‑deleted or the short version
Labels are short strings that you can associate with a run. Labels appear in run lists and in run comparisons by default. Labels can also be used to filter runs in any run-related command.
To label the latest run, use:
guild label get-started
Guild prompts before applying any labels, letting you see which runs are effected before any changes are made:
You are about to label the following runs with 'get-started': [f8d7c6e8] echo.py 2019-03-23 10:18:54 completed Continue? (Y/n)
Enter to apply the label.
Show runs with the
guild runs --label get-started
You can apply labels using a variety of selection options:
- Run indexes and IDs
- Run status
- Marked status
For example, to label all of the
echo.py runs, use:
guild label --operation echo.py get-started
Enter to apply the label.
You can clear labels using the
‑‑clear command line option:
guild label --clear 1:2
This command removes the label from the last two runs.
For more information, see the label command.
Runs may be marked to signify they have special meaning
In this guide you learned about basic run management, including how to:
- Start and stop runs
- List runs
- Show run info
- List and view run files
- Delete and restore runs