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


Through homebrew:

  brew tap hoophq/hoopcli
  brew install hoop

To upgrade it:

  brew upgrade hoop


The command line allows for administering gateway resources and connecting to remote resources. To begin, you need to configure your gateway instance.

hoop config create --api-url https://<gateway-url>

With this configuration in place, you must obtain an access token to interact with the API. The command below will open your browser and redirect you to the identity provider.

hoop login

If you need to clear this configuration, issue the command below.

hoop config clear

If you are unsure about the <gateway-url>, contact your administrator. In our multi-tenant environment, the login will automatically prompt you with a default URL:

After logging in, you can interact with connections. There are two methods for this interaction.

Exec (ad-hoc executions)

The exec command executes ad hoc commands over remote connections. It triggers a command in a remote service, returns the result, and applies all relevant policies and configurations.

hoop exec myconnection -i '/bin/'

Connect (terminal console)

The ‘connect’ command allows you to create an interactive session with a remote resource. Any command that can run in a terminal console can be integrated with Hoop. Here are a few examples:

  • 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

Connect (TCP)

The connect feature can be used to interact with TCP services such as databases. It can be used with an IDE or any native database client. The port is forwarded locally to the end-user, providing a secure connection to remote services.

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

      host= port=5433 user=noop password=noop
ready to accept connections!

The connection is established through a secure tunnel. The connection is encrypted and authenticated using the user’s identity.

Administrator tools

The admin command line tool allows you to manage resources in


hoop login

Get Resources

To view the resources you can get, type hoop admin get --help.

hoop admin get plugins
audit   -       0           6               -
dlp     -       0           6               -

Some resources return a tabular view. If they aren’t available, you can use the -o json option. For example:

hoop admin get reviews -o json |jq .

The tabular view might include extra information, such as connections indicating which agent is linked or which plugin is associated with it.

hoop admin get conn
NAME                        COMMAND                                 TYPE          AGENT                   STATUS    SECRETS   PLUGINS
postgres-demo               [ "psql" "-A" "-F" "\t" "-P" "pa... ]   database      demo-hoopdev-61242e2c   online    -         (8) audit, dlp, editor, indexer, r...
python-weasel-7602          [ "python3" ]                           application   flyioagent              online    -         (7) audit, dlp, editor, indexer, r...
ruby-on-rails-leopon-4156   [ "rails" "runner" "-" ]                application   contoso-macos           offline   -         (7) audit, dlp, editor, indexer, r...
ruby-on-rails-rat-6429      [ "rails" "runner" "-" ]                application   contoso-macos           offline   -         (7) audit, dlp, editor, indexer, r...

To retrieve a single resource

hoop admin get plugins audit

Creating Resources

To view the resources you can create, type hoop admin create --help.


Create an authentication key and start an agent locally.

export HOOP_KEY=$(hoop admin create agent demo)
hoop start agent

List it

hoop admin get agents


The command below establishes a command-line connection with bash, which prints ‘hello hoop’ to the standard output.

The command below requires that you have at least one agent, named demo. To interact with it using hoop exec|connect, the agent must be deployed.

# create it
$ hoop admin create conn hello-hoop -a demo -- bash -c 'echo hello hoop'
# interact it
$ hoop exec hello-hoop
hello hoop

To create a Postgres connection

hoop admin create conn pgdemo -a demo --type database/postgres \
    -e \
    -e PASS=dollar-manger-carouse-HEARTED \
    -e USER=demoreadonly \
    -e PORT=5432

# Interact with it
hoop connect pgdemo

# in another terminal
psql -h 0 --port 5433 dellstore -c 'select now()'

Environment Variables

You could map environment variables to a connection

$ hoop admin create conn demo-bashenv -a demo -e ENVIRONMENT=prod -- \
    bash -c 'echo environment is $ENVIRONMENT'

# interact with it
$ hoop exec demo-bashenv
environment is prod

You could map an environment variables as a file in the filesystem.

$ hoop admin create conn demo-bashfs -a demo -e filesystem:SECRET_FILE=mybigsecret -- \
    bash -c 'echo $SECRET_FILE; cat $SECRET_FILE'

# Interact with it
$ hoop exec demo-bashfs

Using a base64 value as input to environment variables

$ hoop admin create conn demo-b64env -a demo -e b64-envvar:MYENV=$(echo val |base64) -- \
    bash -c 'echo $MYENV'

# Interact with it
$ hoop exec demo-b64env

Deleting Resources

To see the available resources available to delete, type hoop admin delete --help

Delete an agent

hoop admin delete agent demo

Server Info

To see the server information of the gateway

hoop admin serverinfo
Tenant Type:    multitenant
Grpc URL:       grpcs://
Version:        1.21.27
Gateway Commit: e6a0677648b0dbe2a8831fcad4a4e2f0eb8f2d8b
Webapp Commit:  99ce59dc328769c00029befb45503a6cdf96535c

  Log Level:               info
  Go Debug:                http2debug=0
  Admin Username:          admin
  Redact Credentials:      set
  Webhook App Credentials: set
  Ask AI Credentials:      not set
  IDP Audience:            set
  IDP Custom Scopes:       not set
  Postgrest Role:          set