# Union CLI The `union` CLI is the main tool developers use to interact with Union.ai on the command line. ## Installation The recommended way to install the union CLI outside a workflow project is to use [`uv`](https://docs.astral.sh/uv/): ```shell $ uv tool install union ``` This will install the `union` CLI globally on your system [as a `uv` tool](https://docs.astral.sh/uv/concepts/tools/). ## Configure the `union` CLI To configure the `union` CLI to connect to you Union.ai BYOC or Self-managed instance, run the following command: ```shell $ union create login --host ``` where `` is the URL of your Union.ai instance. These command will create the file `~/.union/config.yaml` with the configuration information to connect to the Union.ai instance. See [Getting started > Local setup](https://www.union.ai/docs/v1/union/api-reference/user-guide/getting-started/local-setup) for more details. ## Overriding the configuration file location By default, the `union` CLI will look for a configuration file at `~/.union/config.yaml`. You can override this behavior to specify a different configuration file by setting the `UNION_CONFIG ` environment variable: ```shell export UNION_CONFIG=~/.my-config-location/my-config.yaml ``` Alternatively, you can always specify the configuration file on the command line when invoking `union` by using the `--config` flag: ```shell $ union --config ~/.my-config-location/my-config.yaml run my_script.py my_workflow ``` ## `union` CLI configuration search path The `union` CLI will check for configuration files as follows: First, if a `--config` option is used, it will use the specified config file. Second, the config files pointed to by the following environment variables (in this order): * `UNION_CONFIG` * `UNIONAI_CONFIG` * `UCTL_CONFIG` Third, the following hard-coded locations (in this order): Third, the following hard-coded locations (in this order): * `~/.union/config.yaml` * `~/.uctl/config.yaml` If none of these are present, the CLI will raise an error. ## `union` CLI commands Entrypoint for all the user commands. ```shell union [OPTIONS] COMMAND [ARGS]... ``` ### Options - `-v`, `--verbose` Show verbose messages and exception traces. - `-k`, `--pkgs ` Dot-delineated python packages to operate on. Multiple may be specified (can use commas, or specify the switch multiple times). Please note that this option will override the option specified in the configuration file, or environment variable. - `-c`, `--config ` Path to config file for use within container. --- ### `backfill` The backfill command generates and registers a new workflow based on the input launchplan to run an automated backfill. The workflow can be managed using the UI and can be canceled, relaunched, and recovered. > - `launchplan` refers to the name of the Launchplan. > - `launchplan_version` is optional and should be a valid version for a Launchplan version. ```shell union backfill [OPTIONS] LAUNCHPLAN [LAUNCHPLAN_VERSION] ``` #### Options - `-p`, `--project ` Project for workflow/launchplan. Can also be set through envvar `FLYTE_DEFAULT_PROJECT`. **Default:** `flytesnacks` - `-d`, `--domain ` Domain for workflow/launchplan, can also be set through envvar `FLYTE_DEFAULT_DOMAIN`. **Default:** `'development'` - `-v`, `--version ` Version for the registered workflow. If not specified, it is auto-derived using the start and end date. - `-n`, `--execution-name ` Create a named execution for the backfill. This can prevent launching multiple executions. - `--dry-run` Just generate the workflow - do not register or execute. **Default:** `False` - `--parallel`, `--serial` All backfill steps can be run in parallel (limited by max-parallelism) if using `--parallel`. Else all steps will be run sequentially (`--serial`). **Default:** `False` - `--execute`, `--do-not-execute` Generate the workflow and register, do not execute. **Default:** `True` - `--from-date ` Date from which the backfill should begin. Start date is inclusive. - `--to-date ` Date to which the backfill should run until. End date is inclusive. - `--backfill-window ` Timedelta for number of days, minutes, or hours after the from-date or before the to-date to compute the backfills between. This is needed with from-date / to-date. Optional if both from-date and to-date are provided. - `--fail-fast`, `--no-fail-fast` If set to true, the backfill will fail immediately if any of the backfill steps fail. If set to false, the backfill will continue to run even if some of the backfill steps fail. **Default:** `True` - `--overwrite-cache` Whether to overwrite the cache if it already exists. **Default:** `False` #### Arguments - `LAUNCHPLAN` Required argument. - `LAUNCHPLAN_VERSION` Optional argument. --- ### `build` This command can build an image for a workflow or a task from the command line, for fully self-contained scripts. ```shell union build [OPTIONS] COMMAND [ARGS]... ``` #### Options - `-p`, `--project ` Project to register and run this workflow in. Can also be set through envvar `FLYTE_DEFAULT_PROJECT`. **Default:** `flytesnacks` - `-d`, `--domain ` Domain to register and run this workflow in, can also be set through envvar `FLYTE_DEFAULT_DOMAIN`. **Default:** `'development'` - `--destination-dir ` Directory inside the image where the tar file containing the code will be copied to. **Default:** `'.'` - `--copy-all` [Deprecated, see `--copy`] Copy all files in the source root directory to the destination directory. You can specify `--copy all` instead. **Default:** `False` - `--copy ` Specifies how to detect which files to copy into the image. `all` will behave as the deprecated copy-all flag, `auto` copies only loaded Python modules. **Default:** `'auto'` **Options:** `all | auto` - `-i`, `--image ` Multiple values allowed. Image used to register and run. **Default:** `'cr.union.ai/union/unionai:py3.11-latest' (Serverless), 'cr.flyte.org/flyteorg/flytekit:py3.9-latest' (BYOC)` - `--service-account ` Service account used when executing this workflow. - `--wait`, `--wait-execution` Whether to wait for the execution to finish. **Default:** `False` - `--poll-interval ` Poll interval in seconds to check the status of the execution. - `--dump-snippet` Whether to dump a code snippet instructing how to load the workflow execution using UnionRemote. **Default:** `False` - `--overwrite-cache` Whether to overwrite the cache if it already exists. **Default:** `False` - `--envvars`, `--env ` Multiple values allowed. Environment variables to set in the container, of the format `ENV_NAME=ENV_VALUE`. - `--tags`, `--tag ` Multiple values allowed. Tags to set for the execution. - `--name ` Name to assign to this execution. - `--labels`, `--label ` Multiple values allowed. Labels to be attached to the execution of the format `label_key=label_value`. - `--annotations`, `--annotation ` Multiple values allowed. Annotations to be attached to the execution of the format `key=value`. - `--raw-output-data-prefix`, `--raw-data-prefix ` File Path prefix to store raw output data. Examples are `file://`, `s3://`, `gs://` etc., as supported by fsspec. If not specified, raw data will be stored in the default configured location in remote or locally to the temp file system. - `--max-parallelism ` Number of nodes of a workflow that can be executed in parallel. If not specified, project/domain defaults are used. If 0, then it is unlimited. - `--disable-notifications` Should notifications be disabled for this execution. **Default:** `False` - `-r`, `--remote` Whether to register and run the workflow on a Union deployment. **Default:** `False` - `--limit ` Use this to limit the number of entities to fetch. **Default:** `50` - `--cluster-pool ` Assign newly created execution to a given cluster pool. - `--execution-cluster-label`, `--ecl ` Assign newly created execution to a given execution cluster label. - `--fast` Use fast serialization. The image won’t contain the source code. **Default:** `False` --- ### `build.py` Build an image for [workflow|task] from build.py ```shell union build build.py [OPTIONS] COMMAND [ARGS]... ``` --- ### `cache` Cache certain artifacts from remote registries. ```shell union cache [OPTIONS] COMMAND [ARGS]... ``` #### `model-from-hf` Create a model with NAME from HuggingFace REPO ```shell union cache model-from-hf [OPTIONS] REPO ``` ##### Options - `--artifact-name ` Artifact name to use for the cached model. Must only contain alphanumeric characters, underscores, and hyphens. If not provided, the repo name will be used (replacing '.' with '-'). - `--architecture ` Model architecture, as given in HuggingFace config.json, For non transformer models use XGBoost, Custom etc. - `--task ` Model task, E.g, `generate`, `classify`, `embed`, `score` etc refer to VLLM docs, `auto` will try to discover this automatically - `--modality ` Modalities supported by Model, E.g, `text`, `image`, `audio`, `video` etc refer to VLLM Docs - `--format ` Model serialization format, e.g safetensors, onnx, torchscript, joblib, etc - `--model-type ` Model type, e.g, `transformer`, `xgboost`, `custom` etc. Model Type is important for non-transformer models.For huggingface models, this is auto determined from config.json['model_type'] - `--short-description ` Short description of the model - `--force ` Force caching of the model, pass `--force=1/2/3...` to force cache invalidation - `--wait` Wait for the model to be cached. - `--hf-token-key ` Union secret key with hugging face token - `--union-api-key ` Union secret key with admin permissions - `--cpu ` Amount of CPU to use for downloading, (optionally) sharding, and caching hugging face model - `--gpu ` Amount of GPU to use for downloading (optionally) sharding, and caching hugging face model - `--mem ` Amount of Memory to use for downloading, (optionally) sharding, and caching hugging face model - `--ephemeral-storage ` Amount of Ephemeral Storage to use for downloading, (optionally) sharding, and caching hugging face model - `--accelerator ` The accelerator to use for downloading, (optionally) sharding, and caching hugging face model. **Options:**: `nvidia-l4`, `nvidia-l4-vws`, `nvidia-l40s`, `nvidia-a100`, `nvidia-a100-80gb`, `nvidia-a10g`, `nvidia-tesla-k80`, `nvidia-tesla-m60`, `nvidia-tesla-p4`, `nvidia-tesla-p100`, `nvidia-tesla-t4`, `nvidia-tesla-v100` - `--shard-config ` The engine to shard the model with. A yaml configuration file conforming to [`remote.ShardConfig`](https://www.union.ai/docs/v1/union/api-reference/union-sdk/packages/union.remote/page.md#unionremoteshardconfig). - `-p`, `--project ` Project to operate on - `-d`, `--domain ` Domain to operate on **Default:** `development` - `--help` Show this message and exit. ### `create` Create a resource. ```shell union create [OPTIONS] COMMAND [ARGS]... ``` #### `api-key` Manage API keys. ```shell union create api-key [OPTIONS] COMMAND [ARGS]... ``` ##### `admin` Create an api key. ```shell union create api-key admin [OPTIONS] ``` ###### Options - `--name ` Required Name for API key. --- #### `artifact` Create an artifact with NAME. ```shell union create artifact [OPTIONS] NAME ``` ##### Options - `--version ` Required Version of the artifact. - `-p`, `--partitions ` Partitions for the artifact. - `--short-description ` Short description of the artifact. - `-p`, `--project ` Project to operate on. **Default:** `functools.partial(, previous_default='default')` - `-d`, `--domain ` Domain to operate on. **Default:** `'development'` - `--from_float ` Create an artifact of type (float). - `--from_int ` Create an artifact of type (int). - `--from_str ` Create an artifact of type (str). - `--from_bool ` Create an artifact of type (bool). - `--from_datetime ` Create an artifact of type (datetime). - `--from_duration ` Create an artifact of type (duration). - `--from_json ` Create an artifact of type (struct). - `--from_dataframe ` Create an artifact of type (parquet). - `--from_file ` Create an artifact of type (file). - `--from_dir ` Create an artifact of type (dir). ###### Arguments - `NAME` Required argument. --- #### `login` Log into Union. On Union Serverless run: `union create login --serverless` On Union BYOC run: `union create login --host UNION_TENANT` ```shell union create login [OPTIONS] ``` ##### Options - `--auth ` Authorization method to use. **Options:** `device-flow | pkce` - `--host ` Host to connect to. Mutually exclusive with serverless. - `--serverless` Connect to serverless. Mutually exclusive with host. --- #### `secret` Create a secret with NAME. ```shell union create secret [OPTIONS] NAME ``` ##### Options - `--value ` Secret value. Mutually exclusive with value_file. - `-f`, `--value-file ` Path to file containing the secret. Mutually exclusive with value. - `--project ` Project name. - `--domain ` Domain name. ###### Arguments - `NAME` Required argument. --- #### `workspace` Create workspace. ```shell union create workspace [OPTIONS] CONFIG_FILE ``` ###### Arguments - `CONFIG_FILE` Required argument. --- #### `workspace-config` Create workspace config at CONFIG_FILE. ```shell union create workspace-config [OPTIONS] CONFIG_FILE ``` ##### Options - `--init ` Required. **Options:** `base_image` ###### Arguments - `CONFIG_FILE` Required argument. --- ### `delete` Delete a resource. ```shell union delete [OPTIONS] COMMAND [ARGS]... ``` #### `api-key` Manage API keys. ```shell union delete api-key [OPTIONS] COMMAND [ARGS]... ``` ##### `admin` Delete api key. ```shell union delete api-key admin [OPTIONS] ``` ###### Options - `--name ` Required Name for API key. --- #### `login` Delete login information. ```shell union delete login [OPTIONS] ``` --- #### `secret` Delete secret with NAME. ```shell union delete secret [OPTIONS] NAME ``` ##### Options - `--project ` Project name. - `--domain ` Domain name. ###### Arguments - `NAME` Required argument. --- #### `workspace` Delete workspace with NAME. ```shell union delete workspace [OPTIONS] NAME ``` ##### Options - `--project ` Project name. - `--domain ` Domain name. ###### Arguments - `NAME` Required argument. --- ### `deploy` Deploy a resource. ```shell union deploy [OPTIONS] COMMAND [ARGS]... ``` #### `apps` Deploy application on Union. ```shell union deploy apps [OPTIONS] COMMAND [ARGS]... ``` ##### Options - `-p`, `--project ` Project to run deploy. **Default:** `flytesnacks` - `-d`, `--domain ` Domain to run deploy. **Default:** `'development'` - `-n`, `--name ` Application name to start. --- #### `build.py` Deploy application in build.py. ```shell union deploy apps build.py [OPTIONS] COMMAND [ARGS]... ``` --- ### `execution` The execution command allows you to interact with Union’s execution system, such as recovering/relaunching a failed execution. ```shell union execution [OPTIONS] COMMAND [ARGS]... ``` ##### Options - `-p`, `--project ` Project for workflow/launchplan. Can also be set through envvar `FLYTE_DEFAULT_PROJECT`. **Default:** `flytesnacks` - `-d`, `--domain ` Domain for workflow/launchplan, can also be set through envvar `FLYTE_DEFAULT_DOMAIN`. **Default:** `'development'` - `--execution-id ` Required The execution id. --- #### `recover` Recover a failed execution. ```shell union execution recover [OPTIONS] ``` --- #### `relaunch` Relaunch a failed execution. ```shell union execution relaunch [OPTIONS] ``` --- ### `fetch` Retrieve Inputs/Outputs for a Union execution or any of the inner node executions from the remote server. The URI can be retrieved from the UI, or by invoking the get_data API. ```shell union fetch [OPTIONS] FLYTE-DATA-URI (format flyte://...) DOWNLOAD-TO Local path (optional) ``` ##### Options - `-r`, `--recursive` Fetch recursively, all variables in the URI. This is not needed for directories as they are automatically recursively downloaded. ###### Arguments - `FLYTE-DATA-URI (format flyte://...)` Required argument. - `DOWNLOAD-TO Local path (optional)` Optional argument. --- ### `get` Get a single or multiple remote objects. ```shell union get [OPTIONS] COMMAND [ARGS]... ``` #### `api-key` Manage API keys. ```shell union get api-key [OPTIONS] COMMAND [ARGS]... ``` ##### `admin` Show existing API keys for admin. ```shell union get api-key admin [OPTIONS] ``` --- #### `apps` Get apps. ```shell union get apps [OPTIONS] ``` ##### Options - `--name ` - `--project ` Project name. - `--domain ` Domain name. --- #### `launchplan` Interact with launchplans. ```shell union get launchplan [OPTIONS] LAUNCHPLAN-NAME LAUNCHPLAN-VERSION ``` ##### Options - `--active-only`, `--scheduled` Only return active launchplans. - `-p`, `--project ` Project for workflow/launchplan. Can also be set through envvar `FLYTE_DEFAULT_PROJECT`. **Default:** `flytesnacks` - `-d`, `--domain ` Domain for workflow/launchplan, can also be set through envvar `FLYTE_DEFAULT_DOMAIN`. **Default:** `'development'` - `-l`, `--limit ` Limit the number of launchplans returned. ###### Arguments - `LAUNCHPLAN-NAME` Optional argument. - `LAUNCHPLAN-VERSION` Optional argument. --- #### `secret` Get secrets. ```shell union get secret [OPTIONS] ``` ##### Options - `--project ` Project name. - `--domain ` Domain name. --- #### `workspace` Get workspaces. ```shell union get workspace [OPTIONS] ``` ##### Options - `--name ` - `--project ` Project name. - `--domain ` Domain name. - `--show-details` Show additional details. --- ### `info` ```shell union info [OPTIONS] ``` --- ### `init` Create Union-ready projects. ```shell union init [OPTIONS] PROJECT_NAME ``` ##### Options - `--template