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.37.0.
vh
Usage:
vh [OPTIONS] COMMAND [ARGS]...Options:
--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
vh alias list
Show a list of data aliases in the project.
Usage:
Options:
--count, --limit, -n
integer
How many aliases to show
100
vh data list
Show a list of data in the project.
Usage:
Options:
--count, --limit, -n
integer
How many datums to show
100
vh deployment create-version
Create a new deployment version.
Usage:
Options:
--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
--include-untracked / --no-include-untracked
boolean
When packaging with Git, whether to include untracked (but not ignored) files.
True
vh environments
List all available execution environments.
Usage:
Options:
--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:
Options:
--purge-outputs / --no-purge-outputs
boolean
purge outputs of the executions too
False
vh execution info
Show execution info.
Usage:
vh execution list
Show a list of executions for the project.
Usage:
Options:
--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:
Options:
--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 outputs
List and download execution outputs.
Usage:
Options:
--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:
Options:
--commit, -c
text
The commit to use. Defaults to the current HEAD.
--environment, -e
text
The environment UUID or slug to use (see "vh environments")
--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
--include-untracked / --no-include-untracked
boolean
When packaging with Git, whether to include untracked (but not ignored) files.
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
--time-limit
time_limit
Wall-clock time limit for the execution, e.g. 3600 (seconds) or 1h30m. Overrides the time limit defined for the step in valohai.yaml.
--priority
integer
Priority for the job; higher values mean higher priority. May also be passed as just --priority, implying priority 1.
--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 or slug. (Requires also --environment)
--k8s-cache-volume
text
Kubernetes only. PVC name for cache volume. May be repeated.
--k8s-cache-volume-none
boolean
Kubernetes only. Request no cache volumes, not even if there is a default
False
vh execution ssh
Make SSH Connection to the execution container.
Usage:
Options:
--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:
Options:
--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 watch
Watch execution progress in a console UI.
Usage:
vh init
Interactively initialize a Valohai project.
Usage:
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 login
Log in into Valohai.
Usage:
Options:
--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:
Options:
--yes, -y
boolean
Assume yes to confirmation prompts.
False
vh model describe
Describe a model in Markdown format (for LLM agent use).
Outputs a structured Markdown document to stdout with the model's metadata, tags, associated projects, descriptions, and version history.
MODEL_NAME_OR_ID can be a model name (prefix match) or UUID.
Usage:
Options:
--versions / --no-versions
boolean
Include version listing (default: yes)
True
vh model info
Show details about a model.
MODEL_NAME_OR_ID can be a model name (prefix match) or UUID.
Usage:
vh model list
List models in the catalog.
Usage:
Options:
--count, --limit, -n
integer
How many models to show
100
--tag, -t
text
Filter by tag
--name
text
Filter by name (substring match)
--quiet, -q
boolean
Print only names and IDs, one per line
False
vh model version
Show details about a specific model version.
MODEL_NAME_OR_ID can be a model name (prefix match) or UUID. VERSION_COUNTER_OR_ID can be a version counter number or UUID.
Usage:
Options:
--describe
boolean
Output as Markdown (for LLM agent use)
False
vh model versions
List versions of a model.
MODEL_NAME_OR_ID can be a model name (prefix match) or UUID.
Usage:
Options:
--count, --limit, -n
integer
How many versions to show
100
--status, -s
choice (creating | pending | approved | rejected)
Filter by status
--tag, -t
text
Filter by tag
vh notebook run
Start a notebook execution.
Usage:
Options:
--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:
Options:
-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 convert-to-api
Convert a pipeline configuration to API format (JSON).
This command reads a pipeline from your valohai.yaml configuration and outputs the API-compatible JSON payload that would be sent when running the pipeline.
Usage:
Options:
--commit, -c
text
The commit to use in the API call.
--yaml
text
The path to the configuration YAML file (valohai.yaml) to use.
--indent
integer
JSON indentation level. Use 0 for compact output.
2
vh pipeline list
Show a list of pipelines for the project.
Usage:
Options:
--count, --limit, -n
integer
How many pipelines to show
9001
--deleted, -d
boolean
Show only deleted pipelines
False
--owned, -o
boolean
Show only pipelines that I've created
False
vh pipeline run
Start a pipeline run.
Usage:
Options:
--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
--include-untracked / --no-include-untracked
boolean
When packaging with Git, whether to include untracked (but not ignored) files.
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
--reuse
text
Reuse nodes from an existing pipeline run. COUNTER is a pipeline counter (integer or 'latest'). GLOBs are comma-separated node name patterns to reuse. May be repeated. Example: --reuse=latest:pretrain,mangle
--priority
integer
Priority for the job; higher values mean higher priority. May also be passed as just --priority, implying priority 1.
vh pipeline stop
Stop one or more in-progress pipelines.
Usage:
Options:
--all
boolean
Stop all in-progress pipelines.
False
vh project commits
List the commits for the linked project.
Usage:
vh project create
Create a new project and optionally link it to the directory.
Usage:
Options:
--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:
Options:
--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 list
List environment variables of a project
Usage:
vh project fetch
Fetch new commits for the linked project.
Usage:
vh project link
Link a directory with a Valohai project.
Usage:
Options:
--yes, -y
boolean
Assume yes to confirmation prompts.
False
vh project list
List all projects.
Usage:
vh project open
Open the project's view in a web browser.
Usage:
vh project status
Get the general status of the linked project
Usage:
Options:
--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:
Options:
--yes, -y
boolean
Assume yes to confirmation prompts.
False
vh task list
Show a list of tasks for the project.
Usage:
Options:
--count, --limit, -n
integer
How many tasks to show
9001
--deleted, -d
boolean
Show only deleted tasks
False
--owned, -o
boolean
Show only tasks that I've created
False
vh task run
Start a task.
Usage:
Options:
--commit, -c
text
The commit to use. Defaults to the current HEAD.
--environment, -e
text
The environment UUID or slug to use (see "vh environments")
--image, -i
text
Override the Docker image specified in the step.
--title, -t
text
Title of the task.
--tag
text
Tag the task. May be repeated.
--adhoc, -a
boolean
Upload the current state of the working directory, then run it as an ad-hoc task.
False
--git-packaging, -g / --no-git-packaging, -G
boolean
When creating ad-hoc tasks, whether to allow using Git for packaging directory contents.
True
--include-untracked / --no-include-untracked
boolean
When packaging with Git, whether to include untracked (but not ignored) files.
True
--yaml
text
The path to the configuration YAML (valohai.yaml) file to use.
--var, -v
text
Add environment variable (NAME=VALUE). May be repeated.
--max-queued
integer
Override maximum number of concurrently queued executions.
--on-child-error
choice (continue-and-complete | stop-all-and-error | continue-and-error)
What to do when a child execution errors.
--priority
integer
Priority for the job; higher values mean higher priority. May also be passed as just --priority, implying priority 1.
vh task stop
Stop one or more in-progress tasks.
Usage:
Options:
--all
boolean
Stop all in-progress tasks.
False
vh update-check
Check if there's a newer version of Valohai-CLI available.
Usage:
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:
:param filenames: Path(s) of the Python source code files.
Usage:
Options:
--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:
:param filenames: Path(s) of the Python source code files.
Usage:
Options:
--yaml
text
Path to the YAML file to write to.
Last updated
Was this helpful?