UNOFFICIAL/EXPERIMENTAL
Current commands:
New to cub? Install the cub CLI first. Public catalog packages pull and render anonymously, and you sign in only once a command saves or changes ConfigHub data.
cub variant approve
cub variant create
cub variant demote
cub variant diff
cub variant promote
cub variant uploadThat list is the one the help of cub v0.8.7 prints. An unknown subcommand prints the group help and exits 0, so an exit status does not show that a command exists.
A live run on 2026-10-08 with cub v0.8.7 used approve, create, diff, promote and upload. The run log holds each command and its output. cub variant demote was not run.
Not current local command:
cub variant releasecub variant release may become useful, but user docs should describe it only as planned or candidate work until the CLI exposes it.
What Create Does
cub variant create creates a downstream ConfigHub Space by cloning an upstream Space and its Units.
Current shape:
cub variant create <variant-name> <upstream-space> [flags]The first argument becomes the downstream Space's Variant label. The second argument is the upstream Space slug or UUID.
Example:
cub variant create prod-us-east helm-prometheus-server-only \
--environment Prod \
--region us-east \
--space-pattern 'template:{{.Labels.Component}}-{{.Labels.Variant}}' \
--namespace monitoring-prod \
--unit-delete-gate production-review \
--unit-destroy-gate production-reviewThis creates a derived ConfigHub variant. It does not run Helm again and it does not create a new cub installer base.
The run on 2026-10-08 showed what a clone carries. Without --space-pattern the new Space is named <component>-<variant>. Triggers are not copied, and permissions are copied. When the upstream Space has no trigger selection, the clone gets a selection that points at the upstream Space, so the upstream Space's Triggers still run for the clone. cub variant create has no --dry-run flag.
The clone should preserve the reviewed Unit data. Any post-clone data change needs an explicit allowed mutation path and receipt. If decoded Kubernetes data changes without that receipt, classify it as drift and repair or block the variant before promotion.
Space And Unit Mapping
The upstream Space usually comes from cub installer upload.
cub installer package/base
-> cub installer upload
-> upstream ConfigHub Space with Units
-> cub variant create
-> downstream ConfigHub Space with cloned Units and upstream linksThe downstream Space inherits labels from the upstream Space, then overrides Variant with the first positional argument. Use --environment and --region for common Space label changes.
Use --variant-labels for additional Space labels. Use --space-annotation for Space annotations. Use --target only when the target already exists; it also sets the downstream Space's TargetID annotation. Use --namespace when the upstream Space was uploaded with a placeholder namespace and the derived variant should set a concrete namespace by running set-namespace on cloned Kubernetes/YAML Units.
Unit metadata is separate:
--unit-annotation
--unit-delete-gate
--unit-destroy-gateThese are applied to every cloned Unit. Cloned Units keep their source base labels unless a PostClone trigger or later operation changes them.
Current Boundary
Use cub variant create when the reviewed object set stays the same and the change is post-render ConfigHub metadata, target, gates, links, facts, checks, or approved field fills.
Use cub variant promote when a downstream Space created by cub variant create should catch up with changes in its upstream Space. Start with --dry-run -o mutations so the changed Units and mutation paths are reviewed before writing.
The normal chart lifecycle is:
cub installer recipe/base refresh
-> cub installer upload to the reviewed upstream Space
-> cub variant promote downstream Spaces
-> changeset, approval, apply or OCI/GitOps deliveryThis is a ConfigHub server capability, not a helm-expt-only harness trick. Any component that is represented as an upstream ConfigHub Space with downstream Spaces created by cub variant create can use the same staging and rollout pattern. helm-expt uses Helm charts to show the pattern, but the promotion operation belongs to ConfigHub.
The command being available does not mean every chart/base is already proven safe to promote in production. A chart/base should claim promotion support only after its promotion receipt covers changed Units, added Units, local field ownership, and any deletion or refusal case relevant to that base.
Use cub unit set-protection for explicit field ownership when a downstream variant should keep a local override during future promotion. For example, a production variant can protect one workload's spec.replicas field with --protect, then reopen that path later with --unprotect. The --protect form was run on 2026-10-08 with cub v0.8.7, and the protected path kept its value through a promotion. The run log shows it. --unprotect was not run. The command replaces cub unit set-predicates, which the CLI no longer has.
Use cub variant upload for already-rendered manifests that you want to ingest directly as a ConfigHub variant Space. Every resource becomes its own Unit, except Secrets, which the upload skips and names in its output. In helm-expt's curated catalog path, cub installer upload remains the preferred upload step because the package receipt, base, and recipe proof are part of the contract.
Use a cub installer base variant when Helm must render a different object set, object shape, topology, dependency set, or lifecycle behavior.
Short rule:
Helm render or object shape changes -> cub installer base variant.
Approved post-render ConfigHub refinements -> cub variant create.
Delivery blockers -> delivery prerequisite before GitOps or OCI handoff.Common Mistakes
Do not write current cub variant create examples with --extends or --space. The current create command uses positional arguments:
<variant-name> <upstream-space>Do not use the old --space-name-pattern flag. The current flag is --space-pattern.
Do not describe release as a current cub variant subcommand.