# 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.35.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 ) | |
| `--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 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` |
| `--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 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:**
```
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 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:**
```
vh pipeline convert-to-api [OPTIONS] PIPELINE-NAME
```
**Options:**
| Name | Type | Description | Default |
| ---------------- | ------- | -------------------------------------------------------------- | ------- |
| `--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:**
```
vh pipeline list [OPTIONS]
```
**Options:**
| Name | Type | Description | Default |
| -------------------------- | ------- | ------------------------------------- | ------- |
| `--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:**
```
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 pipeline stop
Stop one or more in-progress pipelines.
**Usage:**
```
vh pipeline stop [OPTIONS] [COUNTERS]...
```
**Options:**
| Name | Type | Description | Default |
| ------- | ------- | ------------------------------- | ------- |
| `--all` | boolean | Stop all in-progress pipelines. | `False` |
### 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 task list
Show a list of tasks for the project.
**Usage:**
```
vh task list [OPTIONS]
```
**Options:**
| Name | Type | Description | Default |
| -------------------------- | ------- | --------------------------------- | ------- |
| `--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 stop
Stop one or more in-progress tasks.
**Usage:**
```
vh task stop [OPTIONS] [COUNTERS]...
```
**Options:**
| Name | Type | Description | Default |
| ------- | ------- | --------------------------- | ------- |
| `--all` | boolean | Stop all in-progress tasks. | `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. | |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.valohai.com/cli-commands.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.