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

ubiops --version

ubiops --help

Authentication¶

Sign in to UbiOps via the CLI. UbiOps supports multiple API host urls. To sign in to a specific API host url, use the --api flag to specify its url (the default is https://api.ubiops.com/v2.1/). If you want to authenticate using an API token, add the --token option as well.

# to authenticate with email and password:
ubiops signin --api "https://api.ubiops.com/v2.1/"

# to authenticate with an API token:
ubiops signin --token --api "https://api.ubiops.com/v2.1/"

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

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

ubiops projects list

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

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.

   Shell (Linux/macOS)Shell (Windows)Yaml

   echo "version_name: v1
   deployment_name: example
   environment: python3-11
   instance_type_group_name: 512 MB + 0.125 vCPU
   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 environment: python3-11 & echo instance_type_group_name: 512 MB + 0.125 vCPU & 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
   environment: python3-11
   instance_type_group_name: 512 MB + 0.125 vCPU
   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
environment: python3-11
instance_type_group_name: 512 MB + 0.125 vCPU
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 environment: python3-11 & echo instance_type_group_name: 512 MB + 0.125 vCPU & 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
environment: python3-11
instance_type_group_name: 512 MB + 0.125 vCPU
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

List deployment versions¶

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

ubiops deployment_versions list -d example

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

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}\"

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}\"

ubiops deployments requests get example -v v1 -id "ID1" -id "ID2" -id "ID3"

Clean up¶

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

ubiops deployment_versions delete v1 -d example

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

ubiops deployments delete example