Command Line

Prerequisites

To get the most out of this guide, you will need to:

Either create an account in our managed instance or deploy your own hoop.dev instance

Installation

MacOS
Linux
Windows
Windows WSL
Manual

Through homebrew:

  brew tap hoophq/brew https://github.com/hoophq/brew.git
  brew install hoop

To upgrade it:

  brew update && brew upgrade hoop

To install or upgrade:

  curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh

Download

Download the latest release of hoop command line for your architecture (usually hoop-windows-amd64) and save it in the Downloads folder

Extract

Extract the file using winrar or winzip

Place it in the right folder

Move the extracted file hoop.exe to the folder C:\Windows\System32\

Check the installation

Open a terminal session and type hoop version if it successfully shows the program’s version it’s installed.

Prerequisites

Install the Windows Terminal https://aka.ms/terminal
Install Ubuntu WSL https://ubuntu.com/wsl
Open the Windows Terminal App
Install and open the Ubuntu typing ubuntu. It should prompt to create a user in the first time

  PS C:\Users\san> ubuntu
  san@DESKTOP-BBQAAEG:~$

gain root access

  sudo su -

To install or upgrade the hoop.dev command line:

  curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh

Already installed? The CLI ships its own version manager under hoop versions. Use hoop versions sync to match the connected gateway, hoop versions upgrade to track the latest release, or hoop versions install <version> to pin a specific version. See hoop versions for details.

Authentication

The authentication process requires either an access token or an API key to interact with the gateway. The following sections outline the various authentication scenarios when using the command line interface.

The authentication process requires knowning the gateway instance URL where the Hoop gateway is running. Our managed instances are hosted under the URL:

https://use.hoop.dev

Contact your administrator if you have a self hosted installation and don’t know this information.

Connection Usage Scenario

This authentication method is recommended for users who need to regularly access and manage resources within their permission scope. Users will authenticate to obtain a valid access token, which remains active based on your identity provider’s expiration policy.

Self Hosted
Managed Instance

This command should be executed only once in your machine. It creates and wipes the file $HOME/.hoop/config.toml in your local machine

hoop config create --api-url https://yourgateway-domain.tld

This command must be executed every time the token expires or the command above is executed.

hoop login

When running the command line interface for the first time, it will create the configuration file $HOME/.hoop/config.toml and prompt you to set the default gateway URL. Your browser will automatically open and redirect you to our identity provider. Subsequent authentication attempts will open your browser and update the access token in your configuration file.After completing authentication, your config.toml will contain a valid access token for continued use of the command line interface.

hoop login

Press enter to leave the defaults
API_URL [https://use.hoop.dev]:

Automation Usage Scenario

When automating Hoop from scripts, CI jobs, or AI agents, use an API Key for authentication and group related invocations with --correlation-id so they can be traced as a single workflow run.

hoop exec postgres-demo \
    --correlation-id task-12345 \
    -i "SELECT * FROM customers WHERE id = 42"

Every hoop exec call that shares the same correlation value is tagged on the session record, which lets you later filter and group the sessions that belong to one logical task (for example, all the queries and API calls an agent made while processing a single ticket).

The correlation ID is a free-form string up to 255 printable ASCII characters. Use whatever identifier your orchestrator already has — a task ID, job ID, workflow run ID, etc.

Programmatic API Access

This authentication method is designed for administrators who need programmatic access to the API for tasks such as managing resource roles, configuring policies, or executing operations within automation pipelines. Programmatic access requires static authentication credentials that can be obtained through the following methods:

API Key

An API Key (prefixed with hpk_) authenticates the CLI headlessly — no browser login, no token expiry. Keys are created from the Web App under Settings → API Keys and inherit the permissions of the groups assigned to them. Persist the key in your local config when bootstrapping a new machine:

hoop config create \
    --api-key hpk_your_key_value \
    --api-url https://yourgateway-domain.tld

Or, if the config already exists, use hoop login --api-key to store the key as the current token:

hoop login --api-key hpk_your_key_value

Refer to the API Keys guide for more information

Service Account

Service Account authentication is available if your identity provider supports the OAuth2 Client Credentials Grant type.

export HOOP_TOKEN="$(/tmp/issue-client-credentials-token-from-idp.sh)"
hoop config create --api-url https://yourgateway-domain.tld

Access tokens obtained from your identity provider typically have an expiration period. To maintain continuous access, create a script that can generate fresh access tokens as needed.

Refer to the Service Account Usage guide for more information.

Using Environment Variables

Another way to use the command line is by exporting the following environment variables:

export HOOP_APIURL=https://use.hoop.dev
export HOOP_GRPCURL=grpcs://use.hoop.dev:8443
export HOOP_TOKEN=<your-access-token-or-api-key>
export HOOP_TLSCA=file:///path/to/ca.pem
# test it
hoop admin get userinfo

When using environment variables, it will ignore the local configuration file $HOME/.hoop/config.yaml

Managing Configuration

Configure your Gateway URL and clear any existent configuration

hoop config create --api-url https://yourgateway-domain.tld

Configure the Gateway URL and the gRPC URL

hoop config create
  --api-url https://yourgateway-domain.tld \
  --grpc-url grpcs://yourgateway-domain.tld:443

This flag is optional and used only to interact with resource roles. The --grpc-url is obtained automatically from the Api when a user Sign In (issue the hoop login command)

Configure the Gateway URL, the gRPC URL and the TLS Certificate Root Certificate

hoop config create
  --api-url https://yourgateway-domain.tld \
  --tls-ca=file:///tmp/ca.pem

# inline configuration
hoop config create
  --api-url https://yourgateway-domain.tld \
  --tls-ca="base64://$(cat /tmp/ca.pem |base64)"

This option should be used if your gateway is running with self signed certificates.

Show API_URL, GRPC_URL and TLS_CA configuration

hoop config view

Show all configuration with the access token (contains sensitive information)

hoop config view --raw

Show sections of configuration

hoop config view api_url
hoop config view grpc_url
hoop config view token
hoop config view tls_ca

Wipe Local Configuration

hoop config clear

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

Prerequisites

Installation

Prerequisites

Authentication

Connection Usage Scenario

Automation Usage Scenario

Programmatic API Access

API Key

Service Account

Using Environment Variables

Managing Configuration

​Prerequisites

​Installation

​Prerequisites

​Authentication

​Connection Usage Scenario

​Automation Usage Scenario

​Programmatic API Access

​API Key

​Service Account

​Using Environment Variables

​Managing Configuration

Prerequisites

Installation

Prerequisites

Authentication

Connection Usage Scenario

Automation Usage Scenario

Programmatic API Access

API Key

Service Account

Using Environment Variables

Managing Configuration