> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Line

> Install and configure the hoop.dev CLI to interact with your applications.

## Prerequisites

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

* Either [create an account in our managed instance](https://use.hoop.dev) or [deploy your own hoop.dev instance](/setup/deployment/overview)

## Installation

<Tabs>
  <Tab title="MacOS">
    Through homebrew:

    ```bash theme={"dark"}
      brew tap hoophq/brew https://github.com/hoophq/brew.git
      brew install hoop
    ```

    To upgrade it:

    ```bash theme={"dark"}
      brew update && brew upgrade hoop
    ```
  </Tab>

  <Tab title="Linux">
    To install or upgrade:

    ```bash theme={"dark"}
      curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh
    ```
  </Tab>

  <Tab title="Windows">
    <Steps>
      <Step title="Download">
        Download the latest release of [hoop command line](https://github.com/hoophq/hoop/releases) for your architecture (usually **hoop-windows-amd64**) and save it in the **Downloads** folder
      </Step>

      <Step title="Extract">
        Extract the file using **winrar** or **winzip**
      </Step>

      <Step title="Place it in the right folder">
        Move the extracted file `hoop.exe` to the folder `C:\Windows\System32\`
      </Step>

      <Step title="Check the installation">
        Open a terminal session and type `hoop version` if it successfully shows the program’s version it’s installed.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows WSL">
    ### Prerequisites

    1. Install the Windows Terminal [https://aka.ms/terminal](https://aka.ms/terminal)
    2. Install Ubuntu WSL [https://ubuntu.com/wsl](https://ubuntu.com/wsl)
    3. Open the Windows Terminal App
    4. Install and open the Ubuntu typing `ubuntu`. It should prompt to create a user in the first time

    ```bash theme={"dark"}
      PS C:\Users\san> ubuntu
      san@DESKTOP-BBQAAEG:~$
    ```

    5. gain root access

    ```bash theme={"dark"}
      sudo su -
    ```

    6. To install or upgrade the hoop.dev command line:

    ```bash theme={"dark"}
      curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh
    ```
  </Tab>

  <Tab title="Manual">
    Check the latest version for your operating system architecture in the [releases page](https://github.com/hoophq/hoop/releases).
  </Tab>
</Tabs>

<Note>
  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](/clients/cli-versions) for details.
</Note>

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

<Note>
  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.
</Note>

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

<Tabs>
  <Tab title="Self Hosted">
    This command should be executed only once in your machine.
    It creates and wipes the file `$HOME/.hoop/config.toml` in your local machine

    ```sh theme={"dark"}
    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.

    ```sh theme={"dark"}
    hoop login
    ```
  </Tab>

  <Tab title="Managed Instance">
    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.

    ```sh theme={"dark"}
    hoop login
    ```

    ```
    Press enter to leave the defaults
    API_URL [https://use.hoop.dev]:
    ```
  </Tab>
</Tabs>

### Automation Usage Scenario

When automating Hoop from scripts, CI jobs, or AI agents, use an [API Key](/setup/apis/api-key) for authentication and group related invocations with `--correlation-id` so they can be traced as a single workflow run.

```sh theme={"dark"}
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).

<Note>
  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.
</Note>

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

```sh theme={"dark"}
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:

```sh theme={"dark"}
hoop login --api-key hpk_your_key_value
```

* Refer to the [API Keys guide for more information](/setup/apis/api-key)

### Service Account

Service Account authentication is available if your identity provider supports the
[OAuth2 Client Credentials Grant type](https://oauth.net/2/grant-types/client-credentials/).

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

<Note>
  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.
</Note>

* Refer to the [Service Account Usage guide for more information](/setup/apis/service-accounts).

### Using Environment Variables

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

```sh theme={"dark"}
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

```sh theme={"dark"}
hoop config create --api-url https://yourgateway-domain.tld
```

* Configure the Gateway URL and the gRPC URL

```sh theme={"dark"}
hoop config create
  --api-url https://yourgateway-domain.tld \
  --grpc-url grpcs://yourgateway-domain.tld:443
```

<Note>
  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)
</Note>

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

```sh theme={"dark"}
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)"
```

<Note>
  This option should be used if your gateway is running with self signed certificates.
</Note>

* Show `API_URL`, `GRPC_URL` and `TLS_CA` configuration

```sh theme={"dark"}
hoop config view
```

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

```sh theme={"dark"}
hoop config view --raw
```

* Show sections of configuration

```sh theme={"dark"}
hoop config view api_url
hoop config view grpc_url
hoop config view token
hoop config view tls_ca
```

* Wipe Local Configuration

```bash theme={"dark"}
hoop config clear
```