Installation and Initial Setup¶

The steps below will get you up and running quickly with h3-cli. These instructions were tested on Linux machines, and generally should work on any POSIX-compliant system with bash support.

It is assumed you already have an account with Horizon3.ai. If not, sign up at https://portal.horizon3ai.com/.

Create an API key¶

An API key is required to access the H3 API. You can create one in the Portal under the User -> Account Settings menu.

When creating an API key you must assign it a role that controls its permissions. The available roles are:

• User: Basic read/write permissions. The API key can run pentests and read results.
• Read-only: The API key can read pentest results, but cannot run pentests.
• NodeZero Runner: A specialized, heavily restricted role designed specifically for NodeZero Runners.

We recommend the User role if you're testing out h3-cli and want to experiment with all its features. After that, you may want to use more restrictive permissions, based on your use case. For example, if you only want to use h3-cli to set up a NodeZero Runner, we recommend using the NodeZero Runner role.

You can easily manage multiple API keys within the same h3-cli install. Learn more here.

❗ Keep your API key secure, as anyone with your API key can access your H3 account. Think of an API key as a username + password rolled into one. Anyone with the API key can access your account from anywhere. h3-cli will store your API key under the $HOME/.h3 directory. This directory is created during installation and configured with permissions such that only you can read or write to it.

Install h3-cli¶

Download and run the installation script:

curl https://downloads.horizon3ai.com/utilities/cli/easy_install.sh | bash -s <your-api-key-here>

This will install the CLI in a new directory, h3-cli. The new directory is created within the directory where the above command is run.

The install script will install dependencies (jq) and create your default h3-cli profile under the $HOME/.h3 directory. Your API key is stored in your h3-cli profile. The directory and profile permissions are restricted so that no other users (besides yourself) can read or write to it.

The install script will ask you to edit your shell profile (for example $HOME/.bash_profile, $HOME/.bash_login, $HOME/.profile, depending on your operating system) to set the following environment variables:

• H3_CLI_HOME: this environment variable is set to the full path of the h3-cli directory. It is used by h3-cli to locate itself and its supporting files.
• PATH: this environment variable specifies the directories to be searched to find a shell command. You can add $H3_CLI_HOME/bin to your PATH to find the h3 command.

After updating your shell profile, you will have to re-login or restart your shell session to pick up the profile changes. You can then verify that you can invoke h3 by running it from the command prompt:

h3

If everything's installed correctly, you should see the h3-cli help text.

Next Step¶