Skip to content

Installation

Prerequisites

  • Go (1.21+) — Required to build the CLI
  • kubectl — Kubernetes CLI, configured with cluster access
  • Helm (3.x) — Used internally for template rendering
  • ArgoCD — Deployed on the target cluster (for GitOps workflows)

Install With Homebrew

Add the Hydra tap:

brew tap hydra-gitops/homebrew-tap https://github.com/hydra-gitops/homebrew-tap

Install the package for your platform:

macOS recommended (source formula):

brew trust --formula hydra-gitops/tap/hydra
brew install hydra-gitops/tap/hydra

Linux recommended (download the released binary from GitHub):

brew trust --formula hydra-gitops/tap/hydra-bin
brew install hydra-gitops/tap/hydra-bin

Hydra ships both artifacts via Homebrew:

  • hydra-bin downloads prebuilt CLI archives from signed GitHub releases and is recommended on Linux.
  • hydra builds from source tarballs in the tap formula and is recommended on macOS.

If you prefer a source build on Linux, this also works:

brew trust --formula hydra-gitops/tap/hydra
brew install hydra-gitops/tap/hydra

Uninstall Homebrew packages with:

brew uninstall hydra-gitops/homebrew-tap/hydra
# or
brew uninstall hydra-gitops/homebrew-tap/hydra-bin
brew untap hydra-gitops/tap

Building the Hydra CLI

cd hydra-go
go build -o hydra ./cli

Move the binary to a directory in your $PATH:

mv hydra /usr/local/bin/
hydra version

Setting Up HYDRA_CONTEXT

Hydra needs to know where your cluster configurations live. Set the HYDRA_CONTEXT environment variable to point at the context directory inside your GitOps repository:

export HYDRA_CONTEXT=/path/to/gitops-repository/clusters/development

Each subdirectory in this path represents one cluster (e.g., dev, cicd, team1, team2).

See Configuration → HYDRA_CONTEXT for details.

Configuring Kubeconfig Mapping

If you manage multiple clusters, create ~/.config/hydra/config.yaml to map cluster directories to specific kubeconfig files:

contexts:
  - path: /path/to/gitops-repository/clusters/prod
    config: ~/.kube/prod.conf
    name: prod-admin
  - path: /path/to/gitops-repository/clusters/test
    config: ~/.kube/test.conf
    name: test-admin

See Configuration → config.yaml for the full reference.

Verifying Connectivity

hydra gitops validate-current-context prod

This verifies that your current kubectl context matches the allowed contexts configured for the cluster. If successful, Hydra can communicate with the cluster API.

Next Steps