Using the H2O CLI

The h2o command line interface is a powerful tool for app developers and other users to interact with the platform.

Configuring the CLI

First you need to configure the CLI so that it knows how to talk to a particular platform deployment.

Before you can do this, make sure that the h2o CLI binary is in your $PATH. If you don't know how to do this, contact your support team.

Next, you will need to configure your CLI by running h2o config setup. You will then be prompted to fill in values for the following fields, shown below with example values:

Endpoint URL: "https://h2o-cloud.example.com"
OIDC URL: "https://auth.example.com"
Client ID: "h2o-cloud-public"

To find out the specific values to enter for these fields according to your environment, you can click on your username on the top-right corner of the App Store home screen, and click CLI & API Access.

cli-api-access

You will see the following screen with the generated values for Endpoint URL, OIDC URL, and Client ID.

cli-generated-values

and after that, you will be asked to visit the Endpoint URL to retrieve a token and paste that in to complete the configuration.

Getting a New Token

You can get a new token without needing to go through the steps of creating an entirely new configuration. This can be done like this: h2o config update-token.

Using Multiple Config Files

You can have as many config files as you wish. When you run h2o config setup, your config will be saved at ~/.h2oai/config/h2o-cli-config.toml. You can have more than one config locally, so you can easily run commands against different environments. For example, you could have both h2o-cli-config.toml as the default which points to your production environment, and then another one called h2o-cli-config-staging.toml which references a different cloud instance. When using the CLI with an alternate config other than the default, you need to start all of your commands with h2o --conf path/to/config.toml or define the environment variable H2OCONFIG to let the CLI know which configuration to use. For example, when bundling an app to deploy to a different environment, you might run h2o --conf ~/.h2oai/h2o-cli-config-staging.toml bundle import or H2OCONFIG=~/.h2oai/h2o-cli-config-staging.toml h2o bundle import. When both the H2OCONFIG environment variable and --conf arguments are provided, the --conf argument take precedence.

Apps

The h2o app [get, list, import, delete, run, update, meta] commands let you see and, when authorized, manage or run available apps.

Listing existing apps

The h2o app list -a command will list all apps visible to the user.

$ h2o app list -a
ID                                    TITLE                        OWNER            CREATED VISIBILITY    TAGS
abc543210-0000-0000-0000-1234567890ab Peak 0.1.1                   user1@h2o.ai     18d     ALL_USERS     Beta
bcd543210-1111-1111-1111-0123456789ab Tour 0.0.15-20200922162859   user2@h2o.ai     20d     ALL_USERS
...

Launching existing apps

To launch an app, the h2o app run <appId> command can be used to launch a new instance of that app. The -v flag can be used with app run to specify app instance visibility settings.

$ h2o app run bcd543210-1111-1111-1111-0123456789ab
ID  22222222-3333-4444-5555-666666666666
URL https://22222222-3333-4444-5555-666666666666.cloud.h2o.ai

Retrieving Metadata from an app

The h2o app meta <appId> command can be used to retreive requirements.txt or packages.txt from an app. The -t flag can be used with app meta to specify REQUIREMENTS,PACKAGES, FILES.

$ h2o app meta  19b2cc66-e1c3-4cfa-96eb-b00cdc8c0da0
h2o-wave==0.16.0
# Packages
$ h2o app meta 19b2cc66-e1c3-4cfa-96eb-b00cdc8c0da0 -t PACKAGES
java
libavcodec58
# Files
$ h2o app meta 1ed9a149-e6ab-41db-ab4a-a64630ad333a -t FILES           
/
LoremIpsum.md
app.toml
lorem.py
requirements.txt
static/
static/icon-example.png

Publishing an app for others to see and launch

To publish an app to the platform, just run h2o bundle import (or h2o bundle and h2o app import <bundle>) in your app source directory. This command will automatically package your current directory into a .wave bundle and import it into the platform.

If you set the visibility to ALL_USERS (via the -v flag), others will be able use h2o app run or the H2OAIC App Store to launch the app.

note

The name-version combination from your app.toml has to be unique and the platform will reject the request if such combination already exists. Therefore, you need to update the name or version in app.toml before each consecutive import command.

$ h2o bundle import -v ALL_USERS
ID              bcd543210-1111-1111-1111-0123456789ab
Title           Peak
Version         0.1.2
Created At      2020-10-13 06:28:03.050226 +0000 UTC
Updated At      2020-10-13 06:28:03.050226 +0000 UTC
Owner           user1@h2o.ai
Visibility      ALL_USERS
Description     Forecast of COVID-19 spread
Tags

Running an app under development

For faster development, running the h2o bundle test command in your app source directory will package your current directory, deploy it and automatically start tailing the logs. On ctrl-c the instance will be terminated and the app will be deleted. The CLI will append a bundle-test suffix to the version in order to ensure resources are cleaned up.

$ h2o bundle test
Waiting for instance to start...

ID  487e6f42-d5e8-4e05-a835-6d73f1488240                        
URL https://487e6f42-d5e8-4e05-a835-6d73f1488240.cloud.h2o.ai   

Use the URL above to open the running App Instance.
Terminate the instance and delete the app bundle with ctrl-c.

To continue and view the instance logs, press enter:

Deploying multiple versions of an app during development

To immediately run your current app source in the platform, just run h2o bundle deploy in your app source directory. This command will automatically package your current directory into a .wave bundle, import it into the platform, and run it.

In the output you will be able to find a URL where you can reach the instance, or visit the "My Instances" in the UI.

note

The CLI will automatically append a suffix to the version in your app.toml so that you can keep iterating on your app without worrying about version conflicts, just don't forget to clean up old instances/versions. Unlike h2o bundle test, resource intensive features like resource volume persistence (enabled by setting ResourceVolumeSize) are disabled.

$ h2o bundle deploy
ID              bcd543210-1111-1111-1111-0123456789ab
Title           Peak
Version         0.1.2-20201013062803
Created At      2020-10-13 06:28:03.050226 +0000 UTC
Updated At      2020-10-13 06:28:03.050226 +0000 UTC
Owner           user1@h2o.ai
Visibility      PRIVATE
Description     Forecast of COVID-19 spread
Tags
ID  22222222-3333-4444-5555-666666666666
URL https://22222222-3333-4444-5555-666666666666.cloud.h2o.ai

Running the app in a cloud-like environment locally

To execute your app in an environment equivalent to that of the platform but on your local machine, just run h2o exec in your app source directory. This will package the app in a temporary .wave bundle and launch it locally using our platform docker image.

Note that this requires that you have docker installed and that you have access to the docker image.

Then navigate to http://localhost:10101/<your main route>.

$ h2o exec
{"level":"info","log_level":"debug","url":"file:///wave_bundle/q-peak.0.1.2.wave","app_root":"/app","venv_root":"/resources","server_path":"/wave/wave","py_module":"peak","tmp":"/tmp","startup_server":true,"version":"latest-20200929","time":"2020-10-13T06:42:21Z","message":"configuration"}
{"level":"info","port":":10101","time":"2020-10-13T06:42:21Z","message":"starting launcher server"}
{"level":"info","executable":"/wave/wave","time":"2020-10-13T06:42:21Z","message":"wave executable found"}
...

Updating app visibility

The h2o app update <appId> -v <visbility> command can be used to modify an existing app's visibility.

Authors who publish a new version of an app may want to de-list the old version. The preferred method to de-list previous versions is to modify the visibility setting to PRIVATE. In fact, it is not possible to fully delete an app if there are instances running and doing so might affect them.

Downloading an app

The h2o app download <appID> [<path>] --extract command can be used to download an app. Authors who publish a version of an app may want to download the app bundle. An optional --extract flag will extract the bundle after download. By default the path will be the name.version of the app, if using the extract flag it will extract to a folder with the same name.

App Instances

The h2o instance [get, list, logs, status, terminate, update] commands let you see and, when authorized, manage available app instances.

Getting instance logs

To see logs of a running instance, just run h2o instance logs <instanceId>; use the flag -f (--follow) to tail the log.

$ h2o instance logs 22222222-3333-4444-5555-666666666666
...
2020/10/27 16:16:34 #
2020/10/27 16:16:34 # ┌─────────────────────────┐
2020/10/27 16:16:34 # │  ┌    ┌ ┌──┐ ┌  ┌ ┌──┐  │ H2O Wave
2020/10/27 16:16:34 # │  │ ┌──┘ │──│ │  │ └┐    │ (version) (build)
2020/10/27 16:16:34 # │  └─┘    ┘  ┘ └──┘  └─┘  │ © 2020 H2O.ai, Inc.
2020/10/27 16:16:34 # └─────────────────────────┘
2020/10/27 16:16:34 #
2020/10/27 16:16:34 # {"address":":10101","t":"listen","webroot":"/wave/www"}
2020/10/27 16:16:34 # {"host":"ws://127.0.0.1:10102","route":"/","t":"relay"}
...

Getting instance status

To see some details about the (K8s) runtime status of a running instance, just run h2o instance status <instanceId>.

$ h2o instance status 22222222-3333-4444-5555-666666666666
Status          CrashLoopBackOff
Reason          Error
Message
Exit Code       1
Restart Count   1
Last Failure    <UNKNOWN>

Updating instance visibility

The h2o instance update <instanceId> -v <visbility> command, much like the app version, can be used to modify an existing running instance's visibility setting.

App Tags

The h2o tag [assign, get, list, remove, update] commands let you see and, when authorized, manage available app tags.

The alias commands let you (if you are an admin) see and manage available aliases. (see Basic Concepts for details on Aliases and their attributes).

Secrets

The h2o secret [create, get, delete, update, list] commands let you see and, when authorized, manage available secrets. (see Authorization for details on ACLs and semantics of the related secrets attributes).

Secret data cannot be directly read by any users via the cli even if they created the secret.

Creating and updating secrets

The h2o secret [create, update] <secretName> command lets you create a secret or update a secret. Based on Kubernetes Secrets.

The --from-literal flag can be used with secrets [create, update] to specify a key=value to be imported into the secret.

The --from-file flag can be used with secrets [create, update] to specify a key=/path/file to import the contents of a file imported into the secret with the specified key.

Secret names have a maximum length of 63 characters and are validated using the following regex ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.

Secret keys have a maximum length of 253 characters and must consist of alphanumeric characters, -, _ or ..

$ h2o secret create secret-name --from-literal=key=value --from-file=myfile=secret_file.txt
Name        secret-name 
Visibility  PRIVATE 
Keys        key, myfile

Updating a secret will replace the current keys and data stored in the secret.

$ h2o secret update secret-name --from-literal=key=newValue --from-file=myfile=secret_file.txt
Name        secret-name 
Visibility  PRIVATE 
Keys        key, myfile

Deleting secrets

The h2o secret delete <secretName> command lets you delete a secret. Secrets cannot be deleted if they are currently in use by any apps.

Aliases

h2o admin alias [assign, create, delete, get, list, promote]

The alias commands let you (if you are an admin) see and manage available aliases. See Basic Concepts for details on Aliases and their attributes.

Listing aliases

h2o admin alias list

Lists relevant details about the current aliases.

Creating aliases

h2o admin alias create <alias> [<instance id>] [<primary>]

Where,

<alias> is the name of the alias (this is what determines the URL, e.g., alias hello results in URL hello.cloud.h2o.ai)
<instance id> (optional) is the instance ID of the instance to assign this tag to at create time (from instance list, instance list -a, or admin instance list)
<primary> (optional) is true or false depending on whether you want the tag to be marked primary at creation time or not

Creates an alias and (optionally) assigns it to an instance.

$ h2o admin alias create hello
ID          11111111-2222-3333-4444-555555555555
Alias       hello
Instance ID 00000000-0000-0000-0000-000000000000
Primary     false
Created At  2022-03-02 12:52:08.900656 +0000 UTC
Updated At  2022-03-02 12:52:08.900656 +0000 UTC

Getting alias information

h2o admin alias get <alias id|name>

Where,

<alias id|name> is the alias name or ID (from admin alias list)

Displays additional information about a specific alias.

$ h2o admin alias get hello
ID          11111111-2222-3333-4444-555555555555
Alias       hello
Instance ID 00000000-0000-0000-0000-000000000000
Primary     false
...

Assigning aliases

h2o admin alias assign <alias id|name> <instance id>

Where,

<alias id|name> is the alias name or ID (from admin alias list)
<instance id> is the instance ID of the instance to assign this tag to at create time (from instance list, instance list -a, or admin instance list)

Assigns an alias to an instance.

$ h2o admin alias assign hello 22222222-3333-4444-5555-666666666666
ID          11111111-2222-3333-4444-555555555555
Alias       hello
Instance ID 22222222-3333-4444-5555-666666666666
Primary     false
...

Note that there can be a slight delay before the change gets propagated.

Assigning an alias will unset its primary bit.

Promoting aliases to primary

h2o admin alias promote <alias id|name>

Where,

<alias id|name> is the alias name or ID (from admin alias list)

Promotes an alias to primary for the corresponding instance.

$ h2o admin alias promote hello
ID          11111111-2222-3333-4444-555555555555
Alias       hello
Instance ID 22222222-3333-4444-5555-666666666666
Primary     true
...

Note that there can be a slight delay before the change gets propagated.

As per Basic Concepts, accessing the instance via other aliases or via its UUID URL will result in a HTTP 302 redirect to the primary alias. If there was another alias marked primary for the same instance, its primary bit will be unset.

Deleting aliases

h2o admin alias delete <alias id|name>

Where,

<alias id|name> is the alias name or ID (from admin alias list)

Deletes an alias.

Note that there can be a slight delay before the change gets propagated.

Using the H2O CLI

Configuring the CLI

Getting a New Token

Using Multiple Config Files

Apps

Listing existing apps

Launching existing apps

Retrieving Metadata from an app

Publishing an app for others to see and launch

note

Running an app under development

Deploying multiple versions of an app during development

note

Running the app in a cloud-like environment locally

Updating app visibility

Downloading an app

App Instances

Getting instance logs

Getting instance status

Updating instance visibility

App Tags

Secrets

Creating and updating secrets

Deleting secrets

Tags

Listing tags

Getting tag information

Assigning tags

Removing tags

Updating tags

Aliases

Listing aliases

Creating aliases

Getting alias information

Assigning aliases

Promoting aliases to primary

Deleting aliases

Configuring the CLI​

Getting a New Token​

Using Multiple Config Files​

Apps​

Listing existing apps​

Launching existing apps​

Retrieving Metadata from an app​

Publishing an app for others to see and launch​

note

Running an app under development​

Deploying multiple versions of an app during development​

note

Running the app in a cloud-like environment locally​

Updating app visibility​

Downloading an app​

App Instances​

Getting instance logs​

Getting instance status​

Updating instance visibility​

App Tags​

Secrets​

Creating and updating secrets​

Deleting secrets​

Tags​

Listing tags​

Getting tag information​

Assigning tags​

Removing tags​

Updating tags​

Aliases​

Listing aliases​

Creating aliases​

Getting alias information​

Assigning aliases​

Promoting aliases to primary​

Deleting aliases​

Configuring the CLI

Getting a New Token

Using Multiple Config Files

Apps

Listing existing apps

Launching existing apps

Retrieving Metadata from an app

Publishing an app for others to see and launch

Running an app under development

Deploying multiple versions of an app during development

Running the app in a cloud-like environment locally

Updating app visibility

Downloading an app

App Instances

Getting instance logs

Getting instance status

Updating instance visibility

App Tags

Secrets

Creating and updating secrets

Deleting secrets

Tags

Listing tags

Getting tag information

Assigning tags

Removing tags

Updating tags

Aliases

Listing aliases

Creating aliases

Getting alias information

Assigning aliases

Promoting aliases to primary

Deleting aliases