varroactl CLI

varroactl manages Varroa from a terminal. Command help is exhaustive:

varroactl --help
varroactl <command> --help

Install and connect

Build the CLI from a source checkout:

make build-cli
./bin/varroactl version --client

Sign in with the browser flow:

varroactl login --server https://varroa.example.com

For automation, pass an API key through standard input:

printf '%s\n' "$VARROA_API_KEY" | varroactl login \
  --server https://varroa.example.com --api-key -

For local or LDAP authentication, use --username and --password-stdin. OIDC installations require the browser flow. See API keys for key lifecycle and handling.

Use contexts

A context stores the server, API key, default namespace, and default cluster. It lets one workstation safely target multiple installations.

varroactl config set-context production \
  --server https://varroa.example.com --namespace team-a --cluster core
varroactl config use-context production
varroactl config get-contexts
varroactl config current-context

Use --context, --server, --namespace, or --cluster for one command without changing the saved context. Flag values override environment variables, which override the config file. VARROACTL_SERVER, VARROACTL_API_KEY, VARROACTL_CONTEXT, and VARROACTL_CONFIG provide environment-based configuration.

Common workflows

# Inspect controllers.
varroactl get controllers -n team-a
varroactl describe controller team-a/controller-a

# Apply a controller definition and observe it.
varroactl create controller -f controller.yaml
varroactl watch -n team-a

# Perform lifecycle work.
varroactl restart controller team-a/controller-a
varroactl power controller team-a/controller-a stopped

# Preview a fleet operation before creating it.
varroactl broodop run restart --selector tier=canary --dry-run

Use Controller lifecycle operations for state changes, Brood operations for fleet actions, and Brood schedules for recurring work.

Work across clusters

Set a context default with varroactl config set-cluster <name>, or pass --cluster <name> to commands that target a cluster. List membership with:

varroactl get clusters

Selector-based brood operations can include --clusters <names> or --clusters all. Explicit multi-cluster names use cluster/namespace/name. See Adding a member cluster.

Output, streams, and safety

Use -o table, wide, json, yaml, or name. Follow controller state with watch, logs, events controller, mite, or activity.

edit, patch, and power can encounter field-ownership conflicts. Use --force only after reviewing field conflict recovery. For plugin-pack and air-gap workflows, use Plugin packs and Air-gapped installation. Use varroactl logout --revoke when a stored key must be revoked.