Hoop.dev

https://hoop.dev/docs
Admin
Hoop.dev is an access gateway for databases and servers with AI-powered automations that provides...
Tokens:65,634
Snippets:565
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Hoop Agent CLI

Source: https://hoop.dev/docs/concepts/agents

Install the Hoop agent CLI binary using the official install script. This script downloads and executes the installer.

```bash
curl -sL https://releases.hoop.dev/release/install-cli.sh | bash
```

--------------------------------

### Start Hoop Agent as System Service

Source: https://hoop.dev/docs/concepts/agents

Run the Hoop agent as a managed background service on Linux/macOS. Set the `HOOP_KEY` environment variable before starting the agent. This command installs, enables, and starts the `hoop-agent` service.

```bash
export HOOP_KEY=<your-key>
hoop agent start
```

--------------------------------

### Connect to Database via CLI

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of a user connecting to a database configured with secrets.

```bash
$ hoop connect prod-postgres
Connected to prod-postgres
psql>
```

--------------------------------

### Install and Upgrade Hoop CLI on Linux

Source: https://hoop.dev/docs/clients/cli

Use the provided shell script to install or upgrade the hoop CLI on Linux.

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

--------------------------------

### Execute Command with Approval

Source: https://hoop.dev/docs/learn/features/access-requests/action

Example of a user initiating a command that requires approval.

```bash
$ hoop exec prod-db -i "UPDATE users SET status = 'inactive' WHERE id = 123"
⣷ Waiting for approval...
```

--------------------------------

### Original Query Result Example

Source: https://hoop.dev/docs/learn/features/live-data-masking

Example of a query result before Live Data Masking is applied.

```text
| name         | email              | ssn         | phone        |
|--------------|--------------------|-------------|--------------|
| John Smith   | john@example.com   | 123-45-6789 | 555-123-4567 |
| Jane Doe     | jane@company.org   | 987-65-4321 | 555-987-6543 |
```

--------------------------------

### Get Hoop Server License Information

Source: https://hoop.dev/docs/setup/license-management

Retrieve details about your current Hoop installation's license, including its validity, type, and expiration date.

```bash
hoop admin serverinfo

(...)
License:
  Key ID:        743420a...79bc
  Type:          enterprise
  Valid:         true
  Issued At:     2024-07-08T09:58:43Z
  Expires At:    2044-07-08T10:58:43Z
  Allowed Hosts: [*.hoop.dev]
  Verify Error:

```

--------------------------------

### Install and Upgrade Hoop CLI on MacOS

Source: https://hoop.dev/docs/clients/cli

Use Homebrew to install or upgrade the hoop CLI on macOS systems.

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

```bash
  brew update && brew upgrade hoop
```

--------------------------------

### Install Hoop License via CLI

Source: https://hoop.dev/docs/setup/license-management

Use this command to install or update your Hoop license using a JSON file. This method allows updating active licenses before expiration.

```bash
hoop admin license install --file /path/to/license.json
```

--------------------------------

### Downgrade Hoop to Open Source License

Source: https://hoop.dev/docs/setup/license-management

This command sequence downloads the default Open Source license and then installs it using the Hoop CLI. This is useful for downgrading from an enterprise license.

```bash
curl -L https://releases.hoop.dev/default-oss-license.json > /tmp/hoop-oss-license.json
hoop admin license install --file /tmp/hoop-oss-license.json
```

--------------------------------

### Configure Windows WSL Environment

Source: https://hoop.dev/docs/clients/cli

Commands for accessing the shell and installing the CLI within a Windows WSL environment.

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

```bash
  sudo su -
```

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

--------------------------------

### Database Credentials with Secret Reference

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of how to securely store database passwords using secret references in a YAML configuration.

```yaml
# Instead of this (insecure):
password: mysecretpassword

# Use this (secure):
password: _envs/vault/secret/databases/prod#password
```

--------------------------------

### SQL Unsafe Update Example

Source: https://hoop.dev/docs/learn/features/guardrails

Demonstrates the risk of executing SQL updates without a WHERE clause.

```sql
-- Intended: Update one user's email
UPDATE users SET email = 'new@email.com' WHERE id = 123;

-- Accidental: Update ALL users (forgot WHERE clause)
UPDATE users SET email = 'new@email.com';
-- 500,000 rows affected 💥
```

--------------------------------

### SSH Keys with Secret Reference

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of securely storing and using SSH private keys with secret references.

```bash
ssh -i _envs/vault/secret/ssh-keys/prod-server#private_key user@server.example.com
```

--------------------------------

### API Keys with Secret Reference

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of injecting API keys for application connections using secret references in a cURL command.

```bash
# Command that needs an API key
curl -H "Authorization: Bearer _envs/vault/secret/api-keys/stripe#key" https://api.stripe.com/v1/charges
```

--------------------------------

### Kubernetes Agent Deployment with Helm

Source: https://hoop.dev/docs/concepts/agents

Deploy the agent into a Kubernetes cluster using the official Helm chart. This command fetches the latest version and installs or upgrades the `hoopagent` release, setting your agent key.

```bash
VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade --install hoopagent \
  https://releases.hoop.dev/release/$VERSION/hoopagent-chart-$VERSION.tgz \
  --set 'config.HOOP_KEY=<your-agent-key>'
```

--------------------------------

### Configure Webhook Plugin

Source: https://hoop.dev/docs/integrations/teams

Initializes the Hoop.dev session and creates the webhooks plugin.

```bash
hoop login
hoop admin create plugin webhooks --overwrite
```

--------------------------------

### Environment Variable Secret Reference Example

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of referencing a secret stored as an environment variable.

```plaintext
_envs/DB_PASSWORD
```

--------------------------------

### Configure Self-Hosted Authentication

Source: https://hoop.dev/docs/clients/cli

Commands to initialize the configuration file and authenticate for self-hosted instances.

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

```sh
hoop login
```

--------------------------------

### HashiCorp Vault Secret Reference Example

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of a secret reference for a password stored in HashiCorp Vault.

```plaintext
_envs/vault/secret/databases/prod-postgres#password
```

--------------------------------

### Authenticate with Managed Instance

Source: https://hoop.dev/docs/clients/cli

Commands and prompts for authenticating with the managed hoop.dev instance.

```sh
hoop login
```

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

--------------------------------

### AWS Secrets Manager Secret Reference Example

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of a secret reference for a password stored in AWS Secrets Manager.

```plaintext
_envs/aws/prod/databases/postgres#password
```

--------------------------------

### Create Connection with Secret Reference

Source: https://hoop.dev/docs/learn/features/secrets-manager

Use this command to create a new connection that references a secret for authentication. The credentials will be fetched from the secret provider at runtime.

```bash
hoop admin create connection prod-postgres \
  --agent default \
  --type postgres \
  -- psql "postgresql://_envs/vault/secret/databases/prod-postgres#username:_envs/vault/secret/databases/prod-postgres#password@db.example.com:5432/myapp"
```

--------------------------------

### Masked Query Result Example

Source: https://hoop.dev/docs/learn/features/live-data-masking

Example of a query result after Live Data Masking is enabled. Sensitive data is replaced with placeholders.

```text
| name         | email              | ssn         | phone        |
|--------------|--------------------|-------------|--------------|
| [REDACTED]   | [REDACTED]         | [REDACTED]  | [REDACTED]   |
| [REDACTED]   | [REDACTED]         | [REDACTED]  | [REDACTED]   |
```

--------------------------------

### Configure Git Integration via CLI

Source: https://hoop.dev/docs/learn/features/runbooks

Configure the Hoop runbooks plugin to point to your Git repository using the CLI. Provide the repository URL and Git access credentials.

```bash
hoop admin create plugin runbooks \
  -c GIT_URL=git@github.com:your-org/runbooks.git \
  -c GIT_SSH_KEY=file://$HOME/.ssh/deploy_key
```

--------------------------------

### Test Connection

Source: https://hoop.dev/docs/learn/features/secrets-manager

After creating a connection that uses secret references, test it with this command to ensure credentials are being fetched correctly.

```bash
hoop connect prod-postgres
```

--------------------------------

### GET /access-request-rules

Source: https://hoop.dev/docs/api-reference/access-request-rules/list-access-request-rules

Retrieves a paginated list of all access request rules defined for the organization.

```APIDOC
## GET /access-request-rules

### Description
List all access request rules for the organization with pagination.

### Method
GET

### Endpoint
/access-request-rules
```

--------------------------------

### Create Runbook SQL Template

Source: https://hoop.dev/docs/learn/features/runbooks

Define a SQL runbook template with a parameterized customer ID lookup. Use Go's text/template syntax for parameters, including descriptions, required fields, and type validation.

```sql
SELECT customer_id, name, email, created_at
FROM customers
WHERE customer_id = {{ .customer_id
    | description "Customer ID to look up"
    | required "Customer ID is required"
    | type "number" }}
```

--------------------------------

### Kubernetes Scale Deployment Runbook

Source: https://hoop.dev/docs/learn/features/runbooks

Scales a Kubernetes deployment using parameters mapped to environment variables.

```bash
# runbooks/k8s/scale-deployment.runbook.sh
# {{ .namespace | description "Kubernetes namespace" | default "default" | asenv "NAMESPACE" }}
# {{ .deployment | description "Deployment name" | required "Deployment required" | asenv "DEPLOYMENT" }}
# {{ .replicas | description "Number of replicas" | type "number" | required "Replicas required" | asenv "REPLICAS" }}

kubectl scale deployment/$DEPLOYMENT \
    --replicas=$REPLICAS \
    --namespace=$NAMESPACE

kubectl rollout status deployment/$DEPLOYMENT --namespace=$NAMESPACE
```

--------------------------------

### Kubernetes Secrets Reference

Source: https://hoop.dev/docs/learn/features/secrets-manager

Example of referencing native Kubernetes secrets for agents running within a Kubernetes environment.

```plaintext
_envs/k8s/my-namespace/db-credentials#password
```

--------------------------------

### View Raw Hoop CLI Configuration

Source: https://hoop.dev/docs/clients/cli

Display the complete Hoop CLI configuration, including sensitive information like the access token. Use with caution.

```sh
hoop config view --raw
```

--------------------------------

### Webhook Event Payload Structure

Source: https://hoop.dev/docs/integrations/aws

Example JSON payload structure for the dbroles.job.finished event sent via webhooks.

```json
{
    "event_type": "dbroles.job.finished",
    "event_payload": {}
}
```

--------------------------------

### Create Connection with Plugin

Source: https://hoop.dev/docs/integrations/teams

Defines a new connection with the webhooks plugin enabled to trigger notifications.

```bash
hoop admin create conn bash -a <agent-name> --overwrite \
  --plugin webhooks \
  --reviewers admin -- bash
```

--------------------------------

### Interact with Slack-Integrated Connections

Source: https://hoop.dev/docs/integrations/slack

Commands to initiate a session or execute commands on a connection that requires Slack approval.

```bash
hoop connect bash
```

```bash
hoop exec bash -i 'ls'
```

--------------------------------

### Parse Runbook Inputs in Python

Source: https://hoop.dev/docs/integrations/aws

Example Python code to retrieve and parse the request and response JSON objects from environment variables. Be cautious about printing sensitive information.

```python
import json, os

requestJson = os.getenv('HOOP_AWS_CONNECT_REQUEST')
responseJson = os.getenv('HOOP_AWS_CONNECT_RESPONSE')

request = json.loads(requestJson)
response = json.loads(responseJson)

print('request db arn: ', request['resource_id'])
print('response status: ', response['status'])
```

--------------------------------

### Fetch Server Info with Hoop API

Source: https://hoop.dev/docs/api-reference/access-request-rules/list-access-request-rules

Obtain the current server configuration by making a GET request to the /serverinfo endpoint. The request must include an Authorization header with a valid Bearer token.

```sh
curl https://use.hoop.dev/api/serverinfo -H "Authorization: Bearer
$ACCESS_TOKEN"
```

--------------------------------

### View Hoop Agent Logs

Source: https://hoop.dev/docs/concepts/agents

View the logs for the Hoop agent system service.

```bash
hoop agent logs
```

--------------------------------

### Configure Slack Integration via Hoop CLI

Source: https://hoop.dev/docs/integrations/slack

Configure the Slack integration using the Hoop command-line interface. Ensure you have logged into your Hoop instance and have the necessary Slack bot and app-level tokens.

```bash
# login to your instance
hoop login
# configure the slack integration
hoop admin create plugin slack \
    --overwrite \
    --config SLACK_BOT_TOKEN=xoxb-... \
    --config SLACK_APP_TOKEN=xapp-...
```

--------------------------------

### View Hoop CLI Configuration

Source: https://hoop.dev/docs/clients/cli

Display the current configuration for API URL, gRPC URL, and TLS CA settings in the Hoop CLI.

```sh
hoop config view
```

--------------------------------

### Hoop CLI Authentication

Source: https://hoop.dev/docs/api-reference/access-request-rules/list-access-request-rules

Use the Hoop CLI to configure the API URL and log in to obtain an access token. Save the token in the default configuration file.

```sh
hoop config create --api-url https://use.hoop.dev

# save the token after authenticating at $HOME/.hoop/config.toml

hoop login

# show token information

hoop config view --raw
```

--------------------------------

### Lint Hoop Runbooks Locally

Source: https://hoop.dev/docs/learn/features/runbooks

Use this command to check your runbook for template parsing errors before deploying. Ensure the path to your runbook is correct.

```bash
hoop runbooks lint path/to/your.runbook.sql
```
Tokens:
Raw