Skip to content

Command Line Interface

UbiOps offers a Command Line Interface (CLI) to interact with the UbiOps API. You can find more information about the CLI on Github.

Installation

The ubiops command line interface is available on PyPi and can be installed using PIP:

pip install ubiops-cli
To check the version of your installation, use:
ubiops --version
If you need help while using the UbiOps CLI, please use the -h or --help option.
ubiops --help

Authentication

Sign in to UbiOps via the CLI. If you want to use an API token to sign in, please add the --token option.

# to authenticate with email and password:
ubiops signin

# to authenticate with an API token:
ubiops signin --token

You will be prompted to fill in your credentials (email + password, or API token if you used the --token option). If you use your email and password to authenticate, a temporary access token is generated in the background, which provides you access for 3 hours.

It's also possible to provide your email and password directly using the --email and --password options. If you are using the --token option, you can use the --password option to provide your API token. Specify your token in the format Token <YOUR_API_KEY>.

To check if you are authorized, use:

ubiops status

If you use your email and password to authenticate, your email will automatically be stored as default user. To check the current user, use:

ubiops user get
To sign out, use:
ubiops signout

Default project

To manage your resources, you need the name of your project. By default, the first project name is selected. To show the current project, use:

ubiops current_project get
To list all your projects, use:
ubiops projects list
To set PROJECT_NAME as your current project, use:
ubiops current_project set PROJECT_NAME

Examples

An example notebook can be found here.

Quickstart

The first step is to download a prepared deployment. Please, use the link to download it.

To list your deployments in your project, use:

ubiops deployments list

Create deployment

The next step is to create the structure of the prepared deployment in your project. The deployment parameters can be specified using a yaml file. Use either the echo shell command below to create the yaml file, or save the content in the second tab below in a file named example_deployment.yaml.

echo "deployment_name: example
deployment_description: UbiOps CLI tutorial.
input_type: structured
input_fields:
  - name: input
    data_type: double
output_type: structured
output_fields:
  - name: output
    data_type: double" > example_deployment.yaml
(echo deployment_name: example & echo deployment_description: UbiOps CLI tutorial. & echo input_type: structured & echo input_fields: & echo   - name: input & echo     data_type: double & echo output_type: structured & echo output_fields: & echo   - name: output & echo    data_type: double) > example_deployment.yaml
deployment_name: example
deployment_description: UbiOps CLI tutorial.
input_type: structured
input_fields:
  - name: input
    data_type: double
output_type: structured
output_fields:
  - name: output
    data_type: double

Click here for more information about the possible deployment parameters.

Create the deployment:

ubiops deployments create -f example_deployment.yaml

Duplicating deployments

If you want to overwrite the deployment name in the yaml file upon deployment creation, you can easily do so by adding a deployment name (.e.g example-duplicate) as argument. This is especially useful if you want to duplicate a deployment: ubiops deployments create -f example_deployment.yaml example-duplicate

Deploy

The next step is to deploy the code. Code can be deployed using two different approaches: a step-by-step approach in which you zip your code, create a new deployment version, and upload the zip, and a second approach which does these steps all together.

Step-by-step approach

  1. The first step is zipping your code directory (CODE_DIRECTORY). Since the zip of this example was already provided, this step could be skipped.

    An ignore file (.ubiops-ignore) could be used to specify files and directories in the code directory that should be excluded in the zip. The structure of the ignore file is assumed to be similar to the well-known .gitignore file.

    ubiops deployments package -dir CODE_DIRECTORY
    

  2. The second step is creating a deployment version. The parameters of the version can both be specified by a yaml file or command options. In this tutorial, a yaml file will be used. Use either the echo shell command below to create the yaml file, or save the content in the second tab below in a file named example_deployment_version.yaml. Since all keys in the two yaml files (deployment creation and version creation) are unique, you could also define them in the same file and use that for both deployment and version creation.

    echo "version_name: v1
    deployment_name: example
    language: python3.7
    memory_allocation: 256
    minimum_instances: 0
    maximum_instances: 1
    maximum_idle_time: 1800
    request_retention_mode: full
    request_retention_time: 3600" > example_deployment_version.yaml
    
    (echo version_name: v1 & echo deployment_name: example & echo language: python3.7 & echo memory_allocation: 256 & echo minimum_instances: 0 & echo maximum_instances: 1 & echo maximum_idle_time: 1800 & echo request_retention_mode: full & echo request_retention_time: 3600) > example_deployment_version.yaml
    
    version_name: v1
    deployment_name: example
    language: python3.7
    memory_allocation: 256
    minimum_instances: 0
    maximum_instances: 1
    maximum_idle_time: 1800
    request_retention_mode: full
    request_retention_time: 3600
    

    Create the deployment version:

    ubiops deployment_versions create -f example_deployment_version.yaml
    

  3. The last step of the step-by-step deployment is uploading the zip to deployment example version v1.

    ubiops deployments upload example -v v1 -z example_deployment_package.zip
    

Single-command approach

To use the single-command approach, the downloaded zip should be unzipped first, as the command expects a directory instead of a zip. After unzipping example_deployment_package.zip, the code directory can be found as deployment_package or example_deployment_package/deployment_package, depending on how you unzip. The root of this code directory contains a deployment.py which is used by UbiOps as entry point of your code. See the Deployment package structure page for more information about the structure of the deployment package.

If you did not specify example_deployment_version.yaml yet, please use the echo shell command below or copy the content of the second tab in a yaml file called example_deployment_version.yaml. Since all keys in the two yaml files (deployment creation and version deployment) are unique, you could also define them in the same file and use that for both deployment creation and version deployment.

echo "version_name: v1
deployment_name: example
language: python3.7
memory_allocation: 256
minimum_instances: 0
maximum_instances: 1
maximum_idle_time: 1800
request_retention_mode: full
request_retention_time: 3600" > example_deployment_version.yaml
(echo version_name: v1 & echo deployment_name: example & echo language: python3.7 & echo memory_allocation: 256 & echo minimum_instances: 0 & echo maximum_instances: 1 & echo maximum_idle_time: 1800 & echo request_retention_mode: full & echo request_retention_time: 3600) > example_deployment_version.yaml
version_name: v1
deployment_name: example
language: python3.7
memory_allocation: 256
minimum_instances: 0
maximum_instances: 1
maximum_idle_time: 1800
request_retention_mode: full
request_retention_time: 3600

Deploy the code in deployment_package (or example_deployment_package/deployment_package) to a new deployment version v2 of deployment example:

ubiops deployments deploy example -v v2 -dir deployment_package/ -f example_deployment_version.yaml
If you would like to store a local copy of the created and uploaded zip, please use the --output_path (or -o) option.

List deployment versions

To list all deployed versions of the example deployment, use:

ubiops deployment_versions list -d example
When your deployment version is available we can create requests.

Creating requests

# Replace DEPLOYMENT_NAME, VERSION_NAME and the input data for your own application.
ubiops deployments requests create DEPLOYMENT_NAME -v VERSION_NAME --data "{\"input_param_1\": \"input_value_1\", \"input_param_2\": \"input_value_2\"}"
# Replace DEPLOYMENT_NAME, VERSION_NAME and the input data for your own application.
ubiops deployments requests create DEPLOYMENT_NAME -v VERSION_NAME --data "plain input"

If you would like to pass an input file (INPUT_FILE) to your deployment, use:

ubiops blobs create -f INPUT_FILE
and use the returned blob ID in the input data of the request.

The example deployment in this tutorial multiplies the input float input by a random number and returns it as output. To create a request input=100 to version v1 (or use version v2), use:

ubiops deployments requests create example -v v1 --data \"{\"input\": 100}\"
When the request finishes, you will see the output of the deployment.

If you would like to create one or more requests without waiting for the result, you could pass the option --batch, which will result in a batch request instead of direct request. It will return the IDs of the created requests, which you can use to get the results later.

For example, create 3 batch requests (or use version v2):

ubiops deployments requests create example -v v1 --batch --data \"{\"input\": 1}\" --data \"{\"input\": 2}\" --data \"{\"input\": 3}\"
and collect the results by using the returned IDs (ID1, ID2 and ID3):
ubiops deployments requests get example -v v1 -id "ID1" -id "ID2" -id "ID3"
Please, note that it is only possible to retrieve requests if the request_retention_mode of the deployment version is 'full' or 'metadata'.

Clean up

You can delete version v1 (or version v2) of deployment example using:

ubiops deployment_versions delete v1 -d example
You will be prompted for confirmation. Press 'y' to confirm. You could also add the -y option.

You can delete the whole deployment (and all its versions) using:

ubiops deployments delete example
You will be prompted for confirmation. Press 'y' to confirm. You could also add the -y option.