Skip to main content

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.

Tags

The tag commands let you see and manage available tags. See Basic Concepts for details on Tags and their attributes.

Listing tags

h2o tag list

Lists relevant details about the current tags.

Getting tag information

h2o tag get <tag id>

Where,

  • <tag id> is the tag ID (from admin tag list)

Displays additional information about a specific tag.

Assigning tags

h2o tag assign <tag id> <app id>

Where,

  • <tag id> is the tag ID (from tag list or admin tag list)
  • <app id> is the application ID (from app list, app list -a, or admin app list)

Assigns a specific tag to a specific version of an application.

Removing tags

h2o tag remove <tag id> <app id>

Where,

  • <tag id> is the tag ID (from tag list or admin tag list)
  • <app id> is the application ID (from app list, app list -a, or admin app list)

Unassigns a specific tag from a specific version of an application.

Updating tags

h2o tag update <tag id> [-n <name> | --name <name>] [-c <color> | --color <color>] [-t <title> | --title <title>] [-d <description> | --description <description>] [-v <visitor role> | --visitor-roles <visitor role>] [-a <visitor admin role> | --admin-roles <visitor admin role>]

Where,

  • <name> is the canonical name for the tag, to be used in app.toml
  • <visitor role> is the OIDC role a user must have to see apps assigned this tag
  • <visitor admin role> is the OIDC role of users who may assign this tag to apps
  • <title>> is the text that appears on the app card in the web interface
  • <color> is the hex value used to colorize the tag in the web interface

Mutates an existing tag.

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.