CLI¶
Gantry’s command-line interface (CLI) is the main way to utilize its functionality.
Run ❯ gantry --help to see a list of all available commands.
Usage: gantry [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
--quiet Don't display the gantry logo.
--log-level [debug|info|warning|error]
The Python log level. [default: warning]
--help Show this message and exit.
Commands:
completion Generate the autocompletion script for gantry for the...
config Configure Gantry for a specific Beaker workspace.
find-gpus Find free GPUs.
follow Follow the logs for a running experiment.
list List recent experiments within a workspace or group.
logs Display the logs for an experiment workload.
open Open the page for a Beaker object in your browser.
run Run an experiment on Beaker.
stop Stop a running workload.
run¶
❯ gantry run
Usage: gantry run [OPTIONS] [ARGS]...
Run an experiment on Beaker.
Example:
$ gantry run --yes --timeout=-1 -- python -c 'print("Hello, World!")'
Options:
--help Show this message and exit.
❯❯❯ Bookkeeping:
-n, --name TEXT A name to assign to the experiment on
Beaker. Defaults to a randomly generated
name.
-d, --description TEXT A description for the experiment.
-w, --workspace TEXT The Beaker workspace to use. If not
specified, your default workspace will be
used.
-b, --budget TEXT The budget account to associate with the
experiment.
--group TEXT A group to assign the experiment to.
❯❯❯ Launch settings:
--show-logs / --no-logs Whether or not to stream the logs to stdout
as the experiment runs. This only takes
effect when --timeout is non-zero.
[default: show-logs]
--timeout INTEGER Time to wait (in seconds) for the experiment
to finish. A timeout of -1 means wait
indefinitely. A timeout of 0 means don't
wait at all. [default: 0]
--allow-dirty Allow submitting the experiment with a dirty
working directory.
-y, --yes Skip all confirmation prompts.
--dry-run Do a dry run only.
--save-spec FILE A path to save the generated YAML Beaker
experiment spec to.
❯❯❯ Constraints:
-c, --cluster TEXT A potential cluster to use. This option can
be used multiple times to allow multiple
clusters. You also specify it as a wildcard,
e.g. '--cluster ai2/*-cirrascale'. If you
don't specify a cluster or the priority, the
priority will default to 'preemptible' and
the job will be able to run on any on-
premise cluster.
--gpu-type TEXT Launch on any cluster with this type of GPU
(e.g. "h100"). Multiple allowed.
--hostname TEXT Hostname constraints to apply to the
experiment spec. This option can be used
multiple times to allow multiple hosts.
❯❯❯ Resources:
--cpus FLOAT Minimum number of logical CPU cores (e.g.
4.0, 0.5).
--gpus INTEGER Minimum number of GPUs (e.g. 1).
--memory TEXT Minimum available system memory as a number
with unit suffix (e.g. 2.5GiB).
--shared-memory TEXT Size of /dev/shm as a number with unit
suffix (e.g. 2.5GiB).
❯❯❯ Inputs:
--beaker-image TEXT The name or ID of an image on Beaker to use
for your experiment. Mutually exclusive with
--docker-image. Defaults to 'ai2/conda' if
neither is set.
--docker-image TEXT The name of a public Docker image to use for
your experiment. Mutually exclusive with
--beaker-image.
--dataset TEXT An input dataset in the form of 'dataset-
name:/mount/location' or 'dataset-
name:sub/path:/mount/location' to attach to
your experiment. You can specify this option
more than once to attach multiple datasets.
-m, --mount TEXT Host directories to mount to the Beaker
experiment. Should be in the form
'{HOST_SOURCE}:{TARGET}' similar to the '-v'
option with 'docker run'.
--weka TEXT A weka bucket to mount in the form of
'bucket-name:/mount/location', e.g.
--weka=oe-training-default:/data
--env TEXT Environment variables to add the Beaker
experiment. Should be in the form
'{NAME}={VALUE}'.
--env-secret, --secret-env TEXT
Environment variables to add the Beaker
experiment from Beaker secrets. Should be in
the form '{NAME}={SECRET_NAME}'.
--dataset-secret TEXT Mount a Beaker secret to a file as a
dataset. Should be in the form
'{SECRET_NAME}:{MOUNT_PATH}'.
--ref TEXT The target git ref to use. Defaults to the
latest commit.
--branch TEXT The target git branch to use. Defaults to
the active branch.
--gh-token-secret TEXT The name of the Beaker secret that contains
your GitHub token. [default: GITHUB_TOKEN]
❯❯❯ Outputs:
--results TEXT Specify the results directory on the
container (an absolute path). This is where
the results dataset will be mounted.
[default: /results]
❯❯❯ Task settings:
-t, --task-name TEXT A name to assign to the task on Beaker.
[default: main]
--priority [low|normal|high|urgent]
The job priority.
--task-timeout TEXT The Beaker job timeout, e.g. "24h". If a job
runs longer than this it will canceled by
Beaker.
--preemptible / --not-preemptible
Mark the job as preemptible or not. If you
don't specify at least one cluster then jobs
will default to preemptible.
--retries INTEGER Specify the number of automatic retries for
the experiment.
❯❯❯ Multi-node:
--replicas INTEGER The number of task replicas to run.
--leader-selection Specifies that the first task replica should
be the leader and populates each task with
'BEAKER_LEADER_REPLICA_HOSTNAME' and
'BEAKER_LEADER_REPLICA_NODE_ID' environment
variables. This is only applicable when '--
replicas INT' and '--host-networking' are
used, although the '--host-networking' flag
can be omitted in this case since it's
assumed.
--host-networking Specifies that each task replica should use
the host's network. When used with '--
replicas INT', this allows the replicas to
communicate with each other using their
hostnames.
--propagate-failure Stop the experiment if any task fails.
--propagate-preemption Stop the experiment if any task is
preempted.
--synchronized-start-timeout TEXT
If set, jobs in the replicated task will
wait this long to start until all other jobs
are also ready.
--skip-tcpxo-setup By default Gantry will configure NCCL for
TCPXO when running multi-node job on
Augusta, but you can use this flag to skip
that step if you need a custom
configuration. If you do use this flag,
you'll probably need to follow all of the
steps documented here:
https://beaker-docs.allen.ai/compute/augusta
.html#distributed-workloads
❯❯❯ Python:
--conda FILE Path to a conda environment file for
reconstructing your Python environment. If
not specified, 'environment.yml' will be
used if it exists.
--venv TEXT The name of an existing conda environment on
the image to use.
--pip FILE Path to a PIP requirements file for
reconstructing your Python environment. If
not specified, 'requirements.txt' will be
used if it exists.
--install TEXT Override the default Python installation
command, e.g. '--install "python setup.py
install"'.
--no-conda If set, gantry will skip setting up conda to
construct a Python environment and instead
will use the default Python environment on
the image.
--no-python If set, gantry will skip setting up a Python
environment altogether.
config¶
❯ gantry config
Usage: gantry config [OPTIONS] COMMAND [ARGS]...
Configure Gantry for a specific Beaker workspace.
Options:
--help Show this message and exit.
Commands:
set-gh-token Set or update Gantry's GitHub token for the workspace.
find-gpus¶
❯ gantry find-gpus
Usage: gantry find-gpus [OPTIONS]
Find free GPUs.
Options:
-a, --all Show all clusters, not just ones with free GPUs.
-g, --gpu-type TEXT Filter by GPU type (e.g. "h100"). Multiple allowed.
--help Show this message and exit.
follow¶
❯ gantry follow
Usage: gantry follow [OPTIONS] [WORKLOAD]
Follow the logs for a running experiment.
Options:
-t, --tail Only tail the logs as opposed to printing all logs so
far.
-l, --latest Get the logs from the latest running experiment (non-
session) workload.
-w, --workspace TEXT The Beaker workspace to pull experiments from. If not
specified, your default workspace will be used.
-a, --author TEXT Pull the latest experiment workload for a particular
author. Defaults to your own account.
--help Show this message and exit.
logs¶
❯ gantry logs
Usage: gantry logs [OPTIONS] WORKLOAD
Display the logs for an experiment workload.
Options:
-r, --replica INTEGER The replica rank to pull logs from.
--task TEXT The name of task to pull logs from.
-t, --tail INTEGER Tail this many lines.
--help Show this message and exit.
list¶
❯ gantry list
Usage: gantry list [OPTIONS]
List recent experiments within a workspace or group. This will only show
experiments launched with Gantry by default, unless '--all' is specified.
Options:
-w, --workspace TEXT The Beaker workspace to pull experiments
from. If not specified, your default
workspace will be used.
-g, --group TEXT The Beaker group to pull experiments from.
-l, --limit INTEGER Limit the number of experiments to display.
Default: 10
-a, --author TEXT Filter by author. Tip: use '--me' instead to
show your own experiments.
--me Only show your own experiments. Mutually
exclusive with '--author'.
-s, --status [submitted|queued|initializing|running|stopping|uploading_results|canceled|succeeded|failed|ready_to_start]
Filter by status. Multiple allowed.
--max-age INTEGER Maximum age of experiments, in days.
Default: 7
--all Show all experiments, not just onces
submitted through Gantry.
--help Show this message and exit.
stop¶
❯ gantry stop
Usage: gantry stop [OPTIONS] [WORKLOAD]...
Stop a running workload.
Options:
-l, --latest Stop your latest experiment (non-session) workload.
-w, --workspace TEXT The Beaker workspace to pull experiments from. If not
specified, your default workspace will be used.
--dry-run Do a dry-run without stopping any experiments.
-y, --yes Skip all confirmation prompts.
--help Show this message and exit.
open¶
❯ gantry open
Usage: gantry open [OPTIONS] [IDENTIFIERS]...
Open the page for a Beaker object in your browser.
Options:
--help Show this message and exit.
completion¶
❯ gantry completion
Usage: gantry completion [OPTIONS] COMMAND [ARGS]...
Generate the autocompletion script for gantry for the specified shell.
See each sub-command's help for details on how to use the generated script.
Options:
--help Show this message and exit.
Commands:
bash Generate the autocompletion script for bash.
fish Generate the autocompletion script for fish.
zsh Generate the autocompletion script for zsh.