CLI Overview

The Hyve CLI manages Kubernetes clusters, Git repositories, workflows, and templates using GitOps principles.

cluster

Cluster lifecycle

module

Provider modules

template

Reusable cluster patterns

workflow

Automated pipelines

git

Repository operations

serve

REST + WebSocket API server

config

Read/update hyve.yaml

tui

Guided TUI

Command Structure

hyve <command> <subcommand> [arguments] [flags]

hyve --help
hyve cluster --help
hyve cluster add --help

Global Flags

These flags are accepted by every command:

Flag	Description
`--home <dir>`	Override the Hyve data directory (default: `~/.hyve`). Also configurable via the `HYVE_HOME` environment variable.

# Use a custom data directory for this invocation
hyve --home /tmp/hyve-test reconcile

# Or set it persistently via environment variable
export HYVE_HOME=/tmp/hyve-test
hyve reconcile

Commands

cluster

hyve cluster list
hyve cluster show <name>
hyve cluster delete <name>
hyve cluster auth <name>
hyve cluster auth sync
hyve cluster deauth <name>

Full reference →

module

hyve module install
hyve module add <source>[@<version>]
hyve module update <source>
hyve module list
hyve module info <source>
hyve module validate
hyve module remove <source>
hyve module init <name>

Full reference →

reconcile

# Local mode — provisions clusters from this machine
hyve reconcile

# CI/CD pipeline mode — uses a checked-out repo path directly
hyve reconcile --path .
hyve reconcile --path /path/to/repo

Reconciliation mode and strict delete are controlled by hyve.yaml in your state repository. See the CI/CD guide.

git

hyve git add <name> --repo-url <url> [--path <dir>]
hyve git list
hyve git use <name>
hyve git current
hyve git path [--repo <name>]
hyve git set-path <new-path> [--repo <name>]
hyve git reset-path [--repo <name>]
hyve git credentials --username <user> --password <token>
hyve git remove <name>

Full reference →

workflow

hyve workflow run <name> [--cluster <cluster>]
hyve workflow list
hyve workflow validate <name>

Full reference →

template

hyve template create <name> --driver <source> --driver-version <ver> --region <region> [--set KEY=VALUE]
hyve cluster create <cluster-name> --template <template> [--region <region>] [--set KEY=VALUE]
hyve template list
hyve template show <name>
hyve template delete <name>
hyve template validate <name>

Full reference →

serve

hyve serve [--port <port>] [--path <repo>] [--host <addr>] [--require-auth] [--open]

Runs hyve as a REST + WebSocket API server — the same operations available through the CLI, available over HTTP for a browser frontend or any other client. --open opens a configured frontend pointed at it once it’s ready — and if a server’s already running, opens the browser against that one instead of starting a second.

Full reference →

config

hyve config get
hyve config set <key> <value>

Reads and updates hyve.yaml — the same object hyve serve’s GET/PATCH /config and Hyve Studio’s Configuration section expose. set writes the field, then commits and pushes.

Full reference →

tui

hyve tui

Launches a full-screen guided TUI. Navigates all command groups — cluster, template, git, workflow — with menus, select lists populated from live data, and back navigation at every level. No flags required.

Full reference →

Environment Variables

Variable	Purpose
`CIVO_TOKEN`	Civo API token (read by the Civo module)
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`	AWS credentials (read by the EKS module via the AWS SDK chain)
`GOOGLE_APPLICATION_CREDENTIALS`	Path to GCP service account JSON (read by the GKE module via ADC)
`AZURE_TENANT_ID` / `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET`	Azure service principal (read by the AKS module)
`HYVE_GIT_TOKEN`	Git authentication token for private repositories
`HYVE_HOME`	Hyve data directory (default: `~/.hyve`). Equivalent to `--home` flag.
`HYVE_PARAM_<KEY>`	Injected into module operations from `cluster.spec.params`
`HYVE_PORT`	Port `hyve serve` listens on. Equivalent to `--port` flag.
`HYVE_AUTH_VALIDATE_URL`	Forward-auth validator endpoint for `hyve serve` (see Server Mode)
`HYVE_AUTH_VALIDATE_TIMEOUT`	Timeout before the forward-auth validator is treated as unreachable (default `3s`)

See the CI/CD guide for how to configure credentials in pipelines.

Common Workflows

Initial setup

# 1. Authenticate with cloud provider CLI (example: Civo)
civo apikey save my-token YOUR_CIVO_TOKEN && civo apikey use my-token

# 2. Add state repository
hyve git add production --repo-url https://github.com/company/hyve-state.git

# 3. Install a module
hyve module add github.com/hyve-modules/civo@v1.0.0

# 4. Create a template
hyve template create my-template \
  --driver github.com/hyve-modules/civo \
  --driver-version v1.0.0 \
  --region PHX1 \
  --set node_size=g4s.kube.medium

# 5. Create a cluster from the template
hyve cluster create my-cluster --template my-template

# 6. Authenticate and connect
hyve cluster auth my-cluster
kubectl get nodes

CI/CD pipeline

# hyve.yaml in state repository root
reconcile:
  mode: cicd
  strictDelete: true   # warns about any cloud cluster missing a clusters/*.yaml — see /docs/guides/cicd

# Engineer pushes desired state (no cloud credentials needed locally)
hyve reconcile

# Pipeline step — provisions the actual cloud resources
hyve reconcile --path .

Delete a cluster

# Sets spec.delete: true, commits, runs reconciliation (runs lifecycle hooks)
hyve cluster delete my-cluster

Shell Completion

Bash

# Add to ~/.bashrc
eval "$(hyve completion bash)"

Zsh

# Add to ~/.zshrc
eval "$(hyve completion zsh)"

Fish

hyve completion fish | source

Troubleshooting

hyve: command not found

sudo mv hyve /usr/local/bin/
# or
export PATH=$PATH:/path/to/hyve

No active repository configured

hyve git add production --repo-url https://github.com/company/hyve-state.git

API authentication failed

# Civo — authenticate with the Civo CLI (writes ~/.civo.json)
civo apikey save my-token YOUR_CIVO_TOKEN
civo apikey use my-token
# or set env var: export CIVO_TOKEN=your_token
# AWS
aws configure
# GCP
gcloud auth application-default login
# Azure
az login

Module not found

# Install all modules referenced by templates
hyve module install

# Or add the specific module
hyve module add github.com/hyve-modules/civo@v1.0.0