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 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

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

Programmatic API Access

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

Static API Key

A Static API Key provides persistent authentication by setting an environment variable in the gateway with a secure random string. Configure the token in your local configuration using this command:

HOOP_TOKEN=<api-key> hoop config create --api-url https://yourgateway-domain.tld

Refer to the API Key Usage 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 connections. 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

Interacting with Resources

The hoop connect command allows you to create an interactive session with a remote resource. The resource include the interactive terminal console or native protocols.

Terminal Console

docker exec
bash
ssh
rails console
python console
kubectl exec
aws ecs execute-command

hoop connect bash-console
connection: bash-console | session: 53ed53f9-a5f9-45e9-bbf5-becd1f44f41e
root@5601881aa15e:/app#

Terminal Ad Hoc Executions

Permit triggering ad hoc executions on a connection.

Issue the command env to a connection with the bash as interpreter

hoop exec bash -i 'env'

Run the script /tmp/myscript.sh using bash as the interpreter

hoop exec bash -f /tmp/myscript.sh

Run the script /tmp/myscript.sh by reading it from the standard input using bash as interpreter

hoop exec bash <<EOF
env |grep -i 'id'
EOF

Native Protocols

The connect feature can be used to interact with native protocols such as databases, SSH, HTTP and TCP. The port is forwarded locally to the end-user, providing a secure connection to remote services.

$ hoop connect pg-prod --port 5433
connection: pg-prod | session: 4619c80f-7166-487c-8c9f-9609e59ae5d6

--------------------postgres-credentials--------------------
      host=127.0.0.1 port=5433 user=noop password=noop
------------------------------------------------------------
ready to accept connections!

The connection is established through a secure tunnel by an encrypted channel when the gateway is setup with TLS. The user identity is always validated when interacting with such resources.

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

Prerequisites

Installation

Prerequisites

Authentication

Connection Usage Scenario

Automation Usage Scenario

Programmatic API Access

Static API Key

Service Account

Using Environment Variables

Managing Configuration

Interacting with Resources

Terminal Console

Terminal Ad Hoc Executions

Native Protocols

​Prerequisites

​Installation

​Prerequisites

​Authentication

​Connection Usage Scenario

​Automation Usage Scenario

​Programmatic API Access

​Static API Key

​Service Account

​Using Environment Variables

​Managing Configuration

​Interacting with Resources

​Terminal Console

​Terminal Ad Hoc Executions

​Native Protocols

Prerequisites

Installation

Prerequisites

Authentication

Connection Usage Scenario

Automation Usage Scenario

Programmatic API Access

Static API Key

Service Account

Using Environment Variables

Managing Configuration

Interacting with Resources

Terminal Console

Terminal Ad Hoc Executions

Native Protocols