CLI

CLI Commands Reference

The valohai-cli package provides a set of commands to interact with the Valohai platform from your local machine. Once installed, the CLI is available as the vh command in your terminal. Below is a reference of available commands and their usage. For convenience, subcommand names may be abbreviated to their unique prefixes.

This documentation is up to date as of valohai-cli 0.34.0.

vh

Usage:

vh [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--debug / --no-debug	boolean	Enable debug logging.	False
--output-format, --table-format	choice (human | csv | tsv | scsv | psv | json)	Set the output format for various data.	human
--valohai-host	text	Override the Valohai API host (default https://app.valohai.com/)
--valohai-token	text	Use this Valohai authentication token
--project	uuid	(Advanced) Override the project ID
--project-mode	text	(Advanced) When using --project, set the project mode
--project-root	directory	(Advanced) When using --project, set the project root directory
--version	boolean	Show the version and exit.

vh alias list

Show a list of data aliases in the project.

Usage:

vh alias list [OPTIONS]

Options:

Name	Type	Description	Default
--count, --limit, -n	integer	How many aliases to show	100

vh data list

Show a list of data in the project.

Usage:

vh data list [OPTIONS]

Options:

Name	Type	Description	Default
--count, --limit, -n	integer	How many datums to show	100

vh deployment create-version

Create a new deployment version.

Usage:

vh deployment create-version [OPTIONS] ENDPOINT-OPTIONS...

Options:

Name	Type	Description	Default
--commit, -c	text	The commit to use. Defaults to the current HEAD.
--deployment, -d	text	The name of the deployment to use.
--var, -v	text	Add environment variable (NAME=VALUE). May be repeated.
--endpoints, -e	text	Names of endpoints enabled in deployment version.
--name, -n	text	Name of the created version (defaults to a name based on the creation date).
--inherit-env-vars / --no-inherit-env-vars	boolean	Use project environment variables in deployment.	True
--adhoc, -a	boolean	Upload the current state of the working directory, then create a deployment version from it.	False
--git-packaging, -g / --no-git-packaging, -G	boolean	When creating ad-hoc executions, whether to allow using Git for packaging directory contents.	True

vh environments

List all available execution environments.

Usage:

vh environments [OPTIONS]

Options:

Name	Type	Description	Default
--gpu, -g / --no-gpu, -G	boolean	Show GPU specifications.	False
--price, -p / --no-price, -P	boolean	Show price.	False
--queue, -q / --no-queue, -Q	boolean	Show queue.	False
--description, -d / --no-description, -D	boolean	Show description.	True

vh execution delete

Delete one or more executions, optionally purging their outputs as well.

Usage:

vh execution delete [OPTIONS] [COUNTERS]...

Options:

Name	Type	Description	Default
--purge-outputs / --no-purge-outputs	boolean	purge outputs of the executions too	False

vh execution info

Show execution info.

Usage:

vh execution info [OPTIONS] COUNTER

vh execution list

Show a list of executions for the project.

Usage:

vh execution list [OPTIONS]

Options:

Name	Type	Description	Default
--status	choice (complete | crashed | created | error | incomplete | queued | started | stopped | stopping)	Filter by status (default: all)
--count, --limit, -n	integer	How many executions to show	9001
--deleted, -d	boolean	Show only deleted executions	False
--owned, -o	boolean	Show only executions that I've created	False

vh execution logs

Show or stream execution event log.

Usage:

vh execution logs [OPTIONS] COUNTER

Options:

Name	Type	Description	Default
--status / --no-status	boolean	Show status messages	True
--stderr / --no-stderr	boolean	Show stderr messages	True
--stdout / --no-stdout	boolean	Show stdout messages	True
--stream / --no-stream	boolean	Watch and wait for new messages?	False
--all / --no-all	boolean	Get all messages? This may take a while.	False

vh execution open

Open an execution in a web browser.

Usage:

vh execution open [OPTIONS] COUNTER

vh execution outputs

List and download execution outputs.

Usage:

vh execution outputs [OPTIONS] COUNTER

Options:

Name	Type	Description	Default
--download, -d	directory	Download files to this directory (by default, don't download). You can use {counter} as a placeholder that will be replaced by the execution's counter number.
--filter-download, -f	text	Download only files matching this glob. Be sure to wrap the value in single quotes (or however appropriate for your shell) to avoid your shell expanding the wildcard, e.g. outputs -f '*.csv'.
--force	boolean	Download all files even if they already exist.	False
--sync, -s	boolean	Keep watching for new output files to download.	False

vh execution run

Start an execution of a step.

Usage:

vh execution run [OPTIONS] STEP-NAME STEP-OPTIONS...

Options:

Name	Type	Description	Default
--commit, -c	text	The commit to use. Defaults to the current HEAD.
--environment, -e	text	The environment UUID or slug to use (see "vh environment list")
--environment-variable-groups	text	Add environment variable group UUIDs.
--image, -i	text	Override the Docker image specified in the step.
--title, -t	text	Title of the execution.
--watch, -w	boolean	Start "exec watch"ing the execution after it starts.	False
--open-browser	boolean	Open default web browser to execution page after it starts.	False
--var, -v	text	Add environment variable (NAME=VALUE). May be repeated.
--tag	text	Tag the execution. May be repeated.
--sync, -s	directory	Download execution outputs to DIRECTORY.
--adhoc, -a	boolean	Upload the current state of the working directory, then run it as an ad-hoc execution.	False
--git-packaging, -g / --no-git-packaging, -G	boolean	When creating ad-hoc tasks, whether to allow using Git for packaging directory contents.	True
--validate-adhoc / --no-validate-adhoc	boolean	Enable or disable validation of adhoc packaged code, on by default	True
--yaml	text	The path to the configuration YAML (valohai.yaml) file to use.
--debug-port	integer	Configure the port for remote debugging the execution via SSH after it starts.
--debug-key-file	path	Path to a public SSH key file for remote debugging the execution after it starts.
--ssh	boolean	Start ssh remote connection for debugging the execution after it starts.	False
--autorestart / --no-autorestart	boolean	Enable Automatic Restart on Spot Instance Interruption	False
--priority	integer	Priority for the job; higher values mean higher priority.
--k8s-cpu-min	float	Kubernetes only. CPU resource request
--k8s-memory-min	integer	Kubernetes only. Memory resource request. Unit is binary megabytes (Mi)
--k8s-cpu-max	float	Kubernetes only. CPU resource request
--k8s-memory-max	integer	Kubernetes only. Memory resource request. Unit is binary megabytes (Mi)
--k8s-device	text	Kubernetes only. Custom device claim. Format: NAME=VALUE. May be repeated for multiple limits.
--k8s-device-none	boolean	Kubernetes only. Request no device claims, not even if there is a default	False
--k8s-preset	text	Kubernetes only. Custom runtime config preset UUID

vh execution ssh

Make SSH Connection to the execution container.

Usage:

vh execution ssh [OPTIONS] COUNTER

Options:

Name	Type	Description	Default
--private-key-file	path	Private SSH key to use for the connection.
--address	text	Address of the container in "ip:port" format. If not provided, the address from the execution will be used.

vh execution stop

Stop one or more in-progress executions.

Usage:

vh execution stop [OPTIONS] [COUNTERS]...

Options:

Name	Type	Description	Default
--all	boolean	Stop all in-progress executions.	False

vh execution summarize

Summarize execution metadata.

Use the global --table-format switch to output JSON/TSV/CSV/...

Usage:

vh execution summarize [OPTIONS] COUNTERS...

vh execution watch

Watch execution progress in a console UI.

Usage:

vh execution watch [OPTIONS] COUNTER

vh init

Interactively initialize a Valohai project.

Usage:

vh init [OPTIONS]

vh lint

Lint (syntax-check) a valohai.yaml file.

The return code of this command will be the total number of errors found in all the files.

Usage:

vh lint [OPTIONS] [FILENAMES]...

vh login

Log in into Valohai.

Usage:

vh login [OPTIONS]

Options:

Name	Type	Description	Default
--username, -u	text	Your Valohai username
--password, -p	text	Your Valohai password
--token, -t	text	A Valohai API token (instead of username and password)
--host, -h	text	Valohai host to login on (for private installations)
--verify-ssl / --no-verify-ssl	boolean	Whether to verify SSL connections (this setting is persisted)	True
--ca-file	text	Path to bundle file or directory with trusted SSL certificates (this setting is persisted)
--yes, -y	boolean	Assume yes to confirmation prompts.	False

vh logout

Remove local authentication token.

Usage:

vh logout [OPTIONS]

Options:

Name	Type	Description	Default
--yes, -y	boolean	Assume yes to confirmation prompts.	False

vh notebook run

Start a notebook execution.

Usage:

vh notebook run [OPTIONS]

Options:

Name	Type	Description	Default
--environment, -e	text	Environment UUID or slug to run the execution in (default = project default environment).
--image, -i	text	Docker image to use for the notebook execution.
--var, -v	text	Add environment variable (NAME=VALUE). May be repeated.

vh parcel

Package a project for offline execution. (Experimental)

Usage:

vh parcel [OPTIONS]

Options:

Name	Type	Description	Default
-d, --destination	directory	Destination directory
-c, --commit	text	Commit to read required Docker image IDs from
--code	choice (bundle | archive | tarball | none)	Package code as a full Git bundle, an archive of Git HEAD, a tarball of the directory or not at all?	bundle
--docker-images / --no-docker-images	boolean	Package Docker images?	True
--valohai-local-run / --no-valohai-local-run	boolean	Download valohai-local-run + deps?	True
--unparcel-script / --no-unparcel-script	boolean	Add unparcel script?	True

vh pipeline run

Start a pipeline run.

Usage:

vh pipeline run [OPTIONS] PIPELINE-NAME PIPELINE-OPTIONS...

Options:

Name	Type	Description	Default
--commit, -c	text	The commit to use. Defaults to the current HEAD.
--title, -t	text	The optional title of the pipeline run.
--adhoc, -a	boolean	Upload the current state of the working directory, then run it as an ad-hoc execution.	False
--git-packaging, -g / --no-git-packaging, -G	boolean	When creating ad-hoc pipelines, whether to allow using Git for packaging directory contents.	True
--yaml	text	The path to the configuration YAML file (valohai.yaml) file to use.
--tag	text	Tag the pipeline. May be repeated.
--environment, -e	text	Override environment UUID or slug

vh project commits

List the commits for the linked project.

Usage:

vh project commits [OPTIONS]

vh project create

Create a new project and optionally link it to the directory.

Usage:

vh project create [OPTIONS]

Options:

Name	Type	Description	Default
--name, -n	text	The name for the project.
--description, -d	text	The description for the project.	``
--owner, -o	text	The owner for the project. Either the name of an organization you belong to, or an organization and team, e.g. myorg:team.
--link, -l / --no-link	boolean	Link the directory to the newly created project? Default yes.	True
--yes, -y	boolean	Assume yes to confirmation prompts.	False

vh project environment-variables create

Add an environment variable to a project

Usage:

vh project environment-variables create [OPTIONS] NAME=VALUE

Options:

Name	Type	Description	Default
--secret / --public	boolean	Set environment variable as a secret. Default value is --public	False

vh project environment-variables delete

Delete one or more environment variables.

Usage:

vh project environment-variables delete [OPTIONS] NAME

vh project environment-variables list

List environment variables of a project

Usage:

vh project environment-variables list [OPTIONS]

vh project fetch

Fetch new commits for the linked project.

Usage:

vh project fetch [OPTIONS]

vh project link

Link a directory with a Valohai project.

Usage:

vh project link [OPTIONS] [PROJECT]

Options:

Name	Type	Description	Default
--yes, -y	boolean	Assume yes to confirmation prompts.	False

vh project list

List all projects.

Usage:

vh project list [OPTIONS]

vh project open

Open the project's view in a web browser.

Usage:

vh project open [OPTIONS]

vh project status

Get the general status of the linked project

Usage:

vh project status [OPTIONS]

Options:

Name	Type	Description	Default
--summary / --no-summary	boolean	Show execution summary	True
--incomplete / --no-incomplete	boolean	Show details of incomplete executions	True

vh project unlink

Unlink a linked Valohai project.

Usage:

vh project unlink [OPTIONS]

Options:

Name	Type	Description	Default
--yes, -y	boolean	Assume yes to confirmation prompts.	False

vh update-check

Check if there's a newer version of Valohai-CLI available.

Usage:

vh update-check [OPTIONS]

vh yaml pipeline

Update a pipeline config(s) in valohai.yaml based on Python source file(s). Python source file is expected to have def main(config: Config) -> Pipeline

Example:

vh yaml pipeline mypipeline.py

:param filenames: Path(s) of the Python source code files.

Usage:

vh yaml pipeline [OPTIONS] FILENAMES...

Options:

Name	Type	Description	Default
--yaml	text	Path to the YAML file to update.

vh yaml step

Update a step config(s) in valohai.yaml based on Python source file(s).

Example:

vh yaml step hello.py

:param filenames: Path(s) of the Python source code files.

Usage:

vh yaml step [OPTIONS] FILENAMES...

Options:

Name	Type	Description	Default
--yaml	text	Path to the YAML file to write to.