CLI Overview

The Hyve CLI manages the full lifecycle of Kubernetes clusters — in local mode, against a directory of YAML files (git-backed or not), or in cluster mode, as a client of a deployed cluster-mode API. Both modes share every command below; which one a given command talks to depends on the active context: one pointing at a hyve-api server (and logged in) uses cluster mode, one pointing at a directory uses local mode.

cluster

Cluster lifecycle

module

Provider modules

template

Reusable cluster patterns

workflow

Automated pipelines

resource

Kubernetes manifests hyve owns

context

Local directories, hyve-api servers, login

environment

Server-side environments

organization

Multi-tenant organizations

reconciling-cluster

Where an organization’s resources live

migrate

Move definitions between modes/clusters

cluster-config

Run the controller/API themselves

Command Structure

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

hyve --help
hyve cluster --help
hyve cluster create --help

Global Flags

Flag	Description
`--home <dir>`	Override the Hyve data directory (default: `~/.hyve`). Also configurable via the `HYVE_HOME` environment variable.
`--org <name>`	Organization to act in for this one command, overriding `hyve organization use` (cluster mode only).
`--env <name>`	hyve-api environment to target for this one command, overriding `hyve environment use` (cluster mode only).

hyve --home /tmp/hyve-test reconcile
# or
export HYVE_HOME=/tmp/hyve-test
hyve reconcile

Commands

reconcile

hyve reconcile                  # active context's directory
hyve reconcile --path .         # explicit path — typical in CI
hyve reconcile --dry-run

A no-op with an explanatory message in cluster mode — the controller reconciles continuously on its own. Mode and strict-delete are controlled by hyve.yaml; see Configuration and the CI/CD guide.

context

Where the CLI’s state lives — a local directory, a hyve-api server, or both — plus login and secrets.

hyve context create <name> [--path <dir>] [--api-url <url>]
hyve context list | current | use <name> | remove <name> | path [name]
hyve context login [--api-url <url>]
hyve context logout | whoami
hyve context secrets list | get | set | unset

Full reference →

environment

Your organization’s server-side environments (cluster mode only).

hyve environment list | create <name> | delete <name>
hyve environment use <name> | unset | current
hyve cluster list --env staging      # one-off override on any command

Full reference →

apply

hyve apply -f <file>

Creates a single resource from a CR-shaped YAML file, auto-detecting its kind (ClusterDefinition/Template/Workflow). Cluster mode only.

migrate

hyve migrate [path] [--write]                       # bulk-import into the logged-in cluster
hyve migrate to-cluster --to <kubeconfig> [--write]  # bootstrap a fresh cluster, no login needed
hyve migrate cluster --from <kc> --to <kc> --write --i-have-stopped-the-source-controller

Three different commands for three different jobs — see the full reference for which one to use when.

cluster

hyve cluster list
hyve cluster show <name>
hyve cluster create <name> --template <template> [--region <region>] [--set KEY=VALUE]
hyve cluster delete <name>
hyve cluster auth <name>
hyve cluster auth sync
hyve cluster deauth <name>
hyve cluster adopt <name> --template <template>
hyve cluster resources <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 →

template

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

Full reference →

workflow

hyve workflow run <name> --cluster <cluster> [--set KEY=VALUE]
hyve workflow list
hyve workflow show <name>
hyve workflow create <name> [--file <yaml>]
hyve workflow validate <name>
hyve workflow delete <name>
hyve workflow install
hyve workflow update <source>

Full reference →

resource

hyve resource list
hyve resource show <name>
hyve resource create <name> [--file <yaml>]
hyve resource delete <name>
hyve resource install

Full reference →

organization

Organizations — the multi-tenant unit on a hyve-api install (cluster mode only): pick the one commands act in, and (superadmin) manage them.

hyve organization list | use <name> | unset | current
hyve cluster list --org widget       # one-off override on any command
hyve organization create <name> | delete <name>
hyve organization migrate <name> (--reconciling-cluster <pool-name> | --home)

Full reference →

reconciling-cluster

The clusters an organization’s resources reconcile on — store several, switch by name (cluster mode only).

hyve reconciling-cluster add <name> --kubeconfig-file <path>
hyve reconciling-cluster list | current
hyve reconciling-cluster use <name> | use --home
hyve reconciling-cluster remove <name>
hyve reconciling-cluster pool add | list          # superadmin

Full reference →

cluster-config

Server-side only — runs inside the deployed controller/API pods, not an everyday end-user command:

hyve cluster-config controller run --namespace hyve-system
hyve cluster-config api run --namespace hyve-system
hyve cluster-config api create-user <username> --role admin

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_HOME`	Hyve data directory (default: `~/.hyve`). Equivalent to `--home` flag.
`HYVE_PARAM_<KEY>`	Injected into module operations from `spec.params`

See the CI/CD guide for configuring credentials in pipelines.

Common Workflows

Initial setup (local mode)

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

# 2. Point hyve at a directory (git-backed or not — see Contexts)
hyve context create production --path ~/repos/hyve-production

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

# 4. Create a template
hyve template create my-template \
  --driver github.com/your-org/hyve-civo-module \
  --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 at the repository root
reconcile:
  mode: cicd
  strictResourceDelete: true

git pull && hyve reconcile --path . && git add -A clusters cluster-state && git commit -m "hyve: reconcile" && git push

Delete a cluster

# Sets spec.delete: true, then reconcile runs onDelete/afterDelete hooks and removes it
hyve cluster delete my-cluster

Troubleshooting

hyve: command not found

go install puts hyve in Go’s bin directory — add it to your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

No context configured

hyve context create production --path ~/repos/hyve-production
hyve context use production

API authentication failed (cloud provider)

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

Cluster-mode login failed

hyve context login --api-url https://hyve-api.example.com
hyve context whoami   # confirm who you're authenticated as, and where

See Login.

Module not found

hyve module install
# or
hyve module add github.com/your-org/hyve-civo-module@v1.0.0