Contexts & Environments

Hyve has two similar-sounding ideas that do different jobs:

	Context	Environment
What it is	This machine’s pointer at where state lives	A named scope inside your organization on a hyve-api server
Lives	Locally, in ~/.hyve/hyve.db	On the server, shared by everyone in the organization
Points at	A local directory, a hyve-api URL, or both	A set of clusters (default, staging, production, …)
Command	hyve context	hyve environment
Modes	Local and cluster mode	Cluster mode only

Contexts

A context is a thin record — a name, a local path, and optionally a hyve-api URL. Hyve has no built-in git functionality: it never clones, pulls, pushes, or commits anything. A context only tracks where your commands read from and write to.

hyve context create prod --path ~/repos/prod-config
hyve context use prod          # subsequent commands read/write here
hyve context current
hyve context list

Local mode: a plain directory, git optional

A local-directory context holds clusters/, templates/, workflows/, resources/, hyve.yaml, and hyve.lock — plain files hyve reconcile reads and writes directly.

Tip

Want git? git clone the directory yourself and git add/git commit/git push around your workflow — typically git pull && hyve reconcile && git add -A && git commit -m "..." && git push, locally or from CI. See Version Control.

Cluster mode: a hyve-api server

hyve context login --api-url https://hyve.example.com   # registers the context too, if it's new

The active context decides the mode: a context with an API URL sends cluster commands to that server; one without works on local files. Switching contexts never logs you out, and logging in never switches which context is active (except that your very first login on a machine activates the context it registers).

Environments

Once you’re in cluster mode, an environment scopes the clusters you work with. Every organization starts with default; create more as you need them. Clusters are created in one environment, and two environments can each hold a cluster with the same name.

hyve environment create staging
hyve environment use staging         # remembered on the active context
hyve cluster list                    # only staging's clusters
hyve cluster show web --env default  # one-off override

Note

Each context that points at a server remembers its own selected environment, so switching contexts switches environments with it. With nothing selected, the server picks when the organization has exactly one environment.

Related

hyve context

Contexts, login, and secrets

hyve environment

Server-side environments

Cluster Mode

Running hyve as a controller + API

Version Control

How git fits in