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.
You will see the following screen with the generated values for Endpoint URL
, OIDC URL
, and Client ID
.
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 (fromadmin 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 (fromtag list
oradmin tag list
)<app id>
is the application ID (fromapp list
,app list -a
, oradmin 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 (fromtag list
oradmin tag list
)<app id>
is the application ID (fromapp list
,app list -a
, oradmin 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., aliashello
results in URLhello.cloud.h2o.ai
)<instance id>
(optional) is the instance ID of the instance to assign this tag to at create time (frominstance list
,instance list -a
, oradmin instance list
)<primary>
(optional) istrue
orfalse
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 (fromadmin 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 (fromadmin alias list
)<instance id>
is the instance ID of the instance to assign this tag to at create time (frominstance list
,instance list -a
, oradmin 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 (fromadmin 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 (fromadmin alias list
)
Deletes an alias.
Note that there can be a slight delay before the change gets propagated.